{"id":"74e197a7-3d73-4f18-aa16-6a67e7a7c8e3","entityType":"agent","slug":"clawhub-sjungwon03-api-to-typemcp","name":"api-to-typemcp","canonicalUrl":"https://www.xpersona.co/agent/clawhub-sjungwon03-api-to-typemcp","canonicalPath":"/agent/clawhub-sjungwon03-api-to-typemcp","generatedAt":"2026-10-11T20:57:35.435Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:10:22.180Z","emptyReason":null},"description":"Use when turning supplied API sources into a safe TypeMCP project.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17dm9vz4bb1bn0gnwk6bprry98b5a29:api-to-typemcp","sourceUrl":"https://clawhub.ai/sjungwon03/api-to-typemcp","homepage":"https://clawhub.ai/sjungwon03/skills/api-to-typemcp","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/sjungwon03/api-to-typemcp","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/sjungwon03/skills/api-to-typemcp","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"api-to-typemcp technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:10:22.180Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:10:22.180Z","emptyReason":null},"stars":null,"forks":null,"downloads":1031,"packageName":null,"latestVersion":"0.2.6","tractionLabel":"1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:10:22.112Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T16:10:22.180Z","lastCrawledAt":"2026-10-11T16:10:22.112Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T16:10:22.112Z","lastVerifiedAt":null,"highlights":[{"version":"0.2.6","createdAt":"2026-08-13T07:09:35.571Z","changelog":"- Bumped version to 0.2.6. - Documentation updates in SKILL.md. - Removed unused file skill-card.md. - Minor changes and cleanup to scripts and test files.","fileCount":52,"zipByteSize":109395},{"version":"0.2.5","createdAt":"2026-08-13T06:33:28.794Z","changelog":"- Update version to 0.2.5. - Documentation change: SKILL.md updated with no workflow or policy changes. - Remove obsolete skill-card.md file.","fileCount":52,"zipByteSize":109023},{"version":"0.2.4","createdAt":"2026-08-13T01:38:25.325Z","changelog":"- Updated to version 0.2.4. - Removed deprecated skill-card.md. - Updated TypeScript package-lock template for consistency. - Minor test and documentation refinements for verification and usage.","fileCount":52,"zipByteSize":109157},{"version":"0.2.3","createdAt":"2026-08-12T23:51:39.449Z","changelog":"- Updated TypeMCP dependency to use the current stable release `@theorvane/type-mcp@0.3.2` instead of `0.2.0`. - Documentation now references the public npm release and exact GitHub commit (`e75bcf6a81ef4df57301b6154a0088845020886f`) for TypeMCP 0.3.2. - Added new runtime documentation test (`tests/test_runtime_documentation.py`). - Removed deprecated `skill-card.md`. - Minor documentation updates and clarifications in workflow and policy descriptions.","fileCount":52,"zipByteSize":108594},{"version":"0.2.2","createdAt":"2026-07-29T05:30:11.325Z","changelog":"**Added agent installation workflow and native config adapters.** - Introduced agent installation option after project generation, supporting \"project only\" (default) or \"project + agent installation\". - Added new scripts for agent client detection, install plan preview/approval/apply, and config codecs; supports Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode natively, plus Hermes and Claude Code via official CLI. - Enforced secret-free, read-only detection; no direct reads of `.env` or secrets; includes one-time plan approval and full rollback on error. - Added comprehensive and isolated tests for all agent installation paths and new core modules. - Updated documentation and SKILL.md with agent install workflows, new safeguards, and usage details. - Removed deprecated skill-card.md and refactored codebase to support agent management and safer extension.","fileCount":51,"zipByteSize":106822},{"version":"0.2.1","createdAt":"2026-07-28T11:48:23.964Z","changelog":"Version 0.2.1 introduces project lockfile generation, expanded execution permissions, and stricter containment during verification. - Added generation of a `package-lock.json` for controlled, reproducible npm installs in generated projects. - Verification now requires and checks contained `npm ci --ignore-scripts` installs, disables inherited proxy/lifecycle settings, and uses a scrubbed workspace. - Changelog and documentation clarify that process containment is not full system isolation; recommend external sandboxing for untrusted dependencies. - Declares new environment variables and system requirements (`python3`, `node`, `npm`) for skill execution and verification. - Strengthened safety gates and updated documentation on runtime policy, output locks, and publication checks.","fileCount":40,"zipByteSize":84036},{"version":"0.2.0","createdAt":"2026-07-28T07:37:05.339Z","changelog":"**Skill api-to-typemcp v0.2.0** introduces a major update with a bundled, self-contained generator engine and TypeScript template delivery. - Added a full Python-based skill engine under `scripts/` for safe manifest, approval, and project generation. - Bundled controlled TypeScript output templates in `templates/`. - Enforced strict safety gates: manifest-first review, HMAC-bound approvals, and secure output/verification policies. - Output projects use only the public, published `@theorvane/type-mcp@0.2.0` runtime. - Added documentation of mandatory workflows, runtime constraints, and verification steps. - Dropped dependency on any external or user-provided generator CLIs.","fileCount":38,"zipByteSize":60303},{"version":"0.1.4","createdAt":"2026-07-27T15:24:21.329Z","changelog":"- Added an explicit \"Current availability\" section clarifying that project generation is blocked until a compatible CLI release is explicitly enabled by policy. - Updated the workflow description to ensure no CLI is installed, invoked, or executed before policy approval, and provided standard user messaging for unsupported CLI scenarios. - Removed the file skill-card.md.","fileCount":3,"zipByteSize":5915}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17dm9vz4bb1bn0gnwk6bprry98b5a29:api-to-typemcp","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17dm9vz4bb1bn0gnwk6bprry98b5a29:api-to-typemcp` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/sjungwon03/api-to-typemcp before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sjungwon03-api-to-typemcp/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sjungwon03-api-to-typemcp/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sjungwon03-api-to-typemcp/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sjungwon03-api-to-typemcp/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sjungwon03-api-to-typemcp/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sjungwon03-api-to-typemcp/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T20:57:35.431Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sjungwon03-api-to-typemcp/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sjungwon03-api-to-typemcp/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sjungwon03-api-to-typemcp/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sjungwon03-api-to-typemcp/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:10:22.180Z","emptyReason":null},"readme":"Skill: api-to-typemcp\n\nOwner: sjungwon03\n\nSummary: Use when turning supplied API sources into a safe TypeMCP project.\n\nTags: latest:0.2.6\n\nVersion history:\n\nv0.2.6 | 2026-08-13T07:09:35.571Z | auto\n\n- Bumped version to 0.2.6.\n- Documentation updates in SKILL.md.\n- Removed unused file skill-card.md.\n- Minor changes and cleanup to scripts and test files.\n\nv0.2.5 | 2026-08-13T06:33:28.794Z | auto\n\n- Update version to 0.2.5.\n- Documentation change: SKILL.md updated with no workflow or policy changes.\n- Remove obsolete skill-card.md file.\n\nv0.2.4 | 2026-08-13T01:38:25.325Z | auto\n\n- Updated to version 0.2.4.\n- Removed deprecated skill-card.md.\n- Updated TypeScript package-lock template for consistency.\n- Minor test and documentation refinements for verification and usage.\n\nv0.2.3 | 2026-08-12T23:51:39.449Z | auto\n\n- Updated TypeMCP dependency to use the current stable release `@theorvane/type-mcp@0.3.2` instead of `0.2.0`.\n- Documentation now references the public npm release and exact GitHub commit (`e75bcf6a81ef4df57301b6154a0088845020886f`) for TypeMCP 0.3.2.\n- Added new runtime documentation test (`tests/test_runtime_documentation.py`).\n- Removed deprecated `skill-card.md`.\n- Minor documentation updates and clarifications in workflow and policy descriptions.\n\nv0.2.2 | 2026-07-29T05:30:11.325Z | auto\n\n**Added agent installation workflow and native config adapters.**\n\n- Introduced agent installation option after project generation, supporting \"project only\" (default) or \"project + agent installation\".\n- Added new scripts for agent client detection, install plan preview/approval/apply, and config codecs; supports Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode natively, plus Hermes and Claude Code via official CLI.\n- Enforced secret-free, read-only detection; no direct reads of `.env` or secrets; includes one-time plan approval and full rollback on error.\n- Added comprehensive and isolated tests for all agent installation paths and new core modules.\n- Updated documentation and SKILL.md with agent install workflows, new safeguards, and usage details.\n- Removed deprecated skill-card.md and refactored codebase to support agent management and safer extension.\n\nv0.2.1 | 2026-07-28T11:48:23.964Z | auto\n\nVersion 0.2.1 introduces project lockfile generation, expanded execution permissions, and stricter containment during verification.\n\n- Added generation of a `package-lock.json` for controlled, reproducible npm installs in generated projects.\n- Verification now requires and checks contained `npm ci --ignore-scripts` installs, disables inherited proxy/lifecycle settings, and uses a scrubbed workspace.\n- Changelog and documentation clarify that process containment is not full system isolation; recommend external sandboxing for untrusted dependencies.\n- Declares new environment variables and system requirements (`python3`, `node`, `npm`) for skill execution and verification.\n- Strengthened safety gates and updated documentation on runtime policy, output locks, and publication checks.\n\nv0.2.0 | 2026-07-28T07:37:05.339Z | auto\n\n**Skill api-to-typemcp v0.2.0** introduces a major update with a bundled, self-contained generator engine and TypeScript template delivery.\n\n- Added a full Python-based skill engine under `scripts/` for safe manifest, approval, and project generation.\n- Bundled controlled TypeScript output templates in `templates/`.\n- Enforced strict safety gates: manifest-first review, HMAC-bound approvals, and secure output/verification policies.\n- Output projects use only the public, published `@theorvane/type-mcp@0.2.0` runtime.\n- Added documentation of mandatory workflows, runtime constraints, and verification steps.\n- Dropped dependency on any external or user-provided generator CLIs.\n\nv0.1.4 | 2026-07-27T15:24:21.329Z | auto\n\n- Added an explicit \"Current availability\" section clarifying that project generation is blocked until a compatible CLI release is explicitly enabled by policy.\n- Updated the workflow description to ensure no CLI is installed, invoked, or executed before policy approval, and provided standard user messaging for unsupported CLI scenarios.\n- Removed the file skill-card.md.\n\nv0.1.3 | 2026-07-24T10:15:13.571Z | auto\n\n- Version bump to 0.1.3.\n- Updated SKILL.md with version metadata.\n- No functional or workflow changes; documentation only.\n\nv0.1.2 | 2026-07-24T09:58:13.586Z | auto\n\n- Bumped version to 0.1.2.\n- Removed the skill-card.md file.\n- Updated SKILL.md with no changes to functionality or workflow.\n\nv0.1.1 | 2026-07-24T07:46:00.468Z | auto\n\n- Added a skill category (integration) to metadata.\n- Removed the file: skill-card.md.\n- No changes to workflow or logic; documentation and metadata improvements only.\n\nv0.1.0 | 2026-07-24T06:50:10.537Z | auto\n\nInitial release of api-to-typemcp.\n\n- Provides a controlled workflow for generating standalone TypeMCP MCP projects from OpenAPI, Swagger, Swagger UI, or documentation sources using type-mcp-api-cli.\n- Enforces strict CLI provenance, isolation, and schema verification; never parses or generates code independently.\n- Requires explicit manifest approval for document-derived or Markdown/HTML sources.\n- Produces clean TypeScript MCP projects with verified dependencies and policy-gated operations.\n- Ensures safety by redacting possible secrets and blocking unsupported or unapproved processes.\n- Includes comprehensive generated-project verification and final publication confirmation steps.\n\nArchive index:\n\nArchive v0.2.6: 52 files, 109395 bytes\n\nFiles: references/agent-mcp-installation.md (5525b), references/type-mcp-runtime.md (2463b), requirements.txt (77b), scripts/agent_clients.py (4854b), scripts/api_to_typemcp.py (15284b), scripts/approval.py (6293b), scripts/config_codecs.py (1631b), scripts/documents.py (3785b), scripts/install_mcp.py (15565b), scripts/install_plan.py (7585b), scripts/intake.py (7300b), scripts/manifest.py (762b), scripts/policy.py (1543b), scripts/render.py (16514b), scripts/structured_specs.py (16750b), scripts/swagger_ui.py (2075b), scripts/verify_generated.py (12511b), skill-card.md (2761b), SKILL.md (10011b), templates/typescript-stdio/package-lock.json.tmpl (86395b), templates/typescript-stdio/package.json.tmpl (463b), templates/typescript-stdio/README.md.tmpl (962b), templates/typescript-stdio/src/api-client.ts.tmpl (1751b), templates/typescript-stdio/src/index.ts.tmpl (255b), templates/typescript-stdio/src/policy.ts.tmpl (1665b), templates/typescript-stdio/tsconfig.json.tmpl (278b), tests/fixtures/api-reference.html (632b), tests/fixtures/api-reference.md (504b), tests/fixtures/mock_upstream.py (3915b), tests/fixtures/petstore.openapi.json (804b), tests/fixtures/petstore.swagger.yaml (579b), tests/fixtures/swagger-ui.html (434b), tests/test_agent_clients.py (3804b), tests/test_agent_installation_docs.py (1522b), tests/test_approval.py (6165b), tests/test_cli_agent_adapters.py (8177b), tests/test_config_codecs.py (1672b), tests/test_document_intake.py (4595b), tests/test_documents.py (6012b), tests/test_engine_cli.py (9325b), tests/test_generated_project_e2e.py (9777b), tests/test_generated_project_static.py (7946b), tests/test_install_mcp.py (6505b), tests/test_install_plan.py (6737b), tests/test_manifest.py (14717b), tests/test_output_safety.py (9128b), tests/test_policy.py (1512b), tests/test_render.py (10488b), tests/test_runtime_documentation.py (2455b), tests/test_swagger_ui.py (3218b), tests/test_verify_generated_security.py (4205b), _meta.json (133b)\n\nFile v0.2.6:SKILL.md\n\n---\nname: api-to-typemcp\ndescription: Use when turning supplied API sources into a safe TypeMCP project.\nversion: 0.2.6\ncategory: integration\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [mcp, api, openapi, swagger, code-generation, type-mcp]\n    related_skills: []\n  openclaw:\n    requires:\n      bins: [python3, node, npm]\n    envVars:\n      - name: TYPE_MCP_APPROVAL_STATE_DIR\n        required: false\n        description: Isolated directory for single-use generation approvals.\n      - name: TYPE_MCP_BASE_URL\n        required: false\n        description: Local test upstream used only by contained verification.\n---\n\n# API to TypeMCP\n\n## Overview\n\nThis released skill is a complete, bundled generator delivery unit. Its **bundled skill engine** is in `scripts/`, its controlled TypeScript output templates are in `templates/`, and its public TypeMCP runtime constraints are in [references/type-mcp-runtime.md](references/type-mcp-runtime.md).\n\nGenerated projects use the current published `@theorvane/type-mcp@0.3.2` release line and only its public package exports; they never copy TypeMCP source or use local, `file:`, `git:`, `link:`, or private runtime APIs. The npm registry `gitHead` and GitHub Release `v0.3.2` both resolve to `e75bcf6a81ef4df57301b6154a0088845020886f`.\n\n## When to use\n\nUse this skill with a **supplied local** OpenAPI 3.x / Swagger 2.0 JSON/YAML file, supplied Swagger UI HTML, or supplied Markdown/HTML API reference. Do not use it to crawl a bare origin, infer undocumented operations, make mutating calls by default, or publish without explicit final confirmation.\n\n## Execution permissions and containment boundary\n\nThe engine reads only the user-supplied source and files bundled with this skill. It writes only the caller-created output directory and the optional `TYPE_MCP_APPROVAL_STATE_DIR`; it never modifies an upstream API or publishes a repository without the separate explicit gates below.\n\nThe engine invokes `python3`. Optional generated-project verification additionally invokes `npm` and `node`, uses a fresh temporary workspace, passes a credential-scrubbed environment, disables inherited npm proxy settings and lifecycle scripts, and installs exactly the generated `package-lock.json` graph with `npm ci`. That install requires outbound access to the npm registry; the generator itself performs no network fetch or crawling, and the smoke test targets only a caller-provided local test upstream.\n\nThis verifier is **process containment**, not a claim of kernel or network isolation. Run it in a container, VM, or an equivalent host sandbox when the generated project or its dependency installation is untrusted.\n\n## Bundled engine workflow\n\nRun the engine through its installed skill-relative path. Set `SKILL_DIR` to the directory containing this `SKILL.md`; create a **controlled temporary output directory** yourself and keep it empty.\n\n```bash\nSKILL_DIR=\"/absolute/path/to/api-to-typemcp\"\nSOURCE=\"/absolute/path/to/supplied-openapi.json\"\nOUTPUT=\"$(mktemp -d -t api-to-typemcp-output.XXXXXX)\"\nSTATE=\"$(mktemp -d -t api-to-typemcp-state.XXXXXX)\"\nexport TYPE_MCP_APPROVAL_STATE_DIR=\"$STATE\"\n\n# 1. Inspect and build the exact secret-free manifest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" inspect --file \"$SOURCE\" --json\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest --file \"$SOURCE\" --json > manifest.json\nDIGEST=\"$(python3 -c 'import json; print(json.load(open(\"manifest.json\"))[\"digest\"])')\"\n\n# 2. Review the manifest, then explicitly approve precisely that digest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" approve \\\n  --file \"$SOURCE\" --manifest-digest \"$DIGEST\"\n\n# 3. Render only after approval, with an exact digest confirmation.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" generate \\\n  --file \"$SOURCE\" --output \"$OUTPUT\" \\\n  --confirm-manifest-digest \"$DIGEST\"\n```\n\nFor supplied Markdown or HTML, add an explicit origin; no page is fetched or crawled:\n\n```bash\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest \\\n  --file \"/absolute/path/to/reference.md\" \\\n  --base-url \"https://api.example.test\" --json\n```\n\nSwagger UI discovery is performed by `inspect` in-memory and returns only an explicit configured spec reference. The user must separately supply that structured spec; do not fetch it automatically.\n\n## Mandatory safety gates\n\n1. **Manifest first.** Treat every source as untrusted. Review canonical secret-free manifest data before generation.\n2. **Receipt gate.** `approve` issues a HMAC-protected, digest-bound, single-use receipt. A changed, expired, tampered, or already-consumed receipt stops `generate`.\n3. **Output gate.** The output directory must already exist and be empty unless `--replace` is explicitly supplied. Symlinks and `..` traversal are rejected.\n4. **Runtime policy.** `GET`/`HEAD`/`OPTIONS` are read operations. `POST`/`PUT`/`PATCH`/`DELETE` are protected writes and require exact known IDs in `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS` **before URL, query, headers, body, authentication, or dispatch**. Unknown methods deny.\n5. **Containment.** Verify generated projects in a scrubbed temporary workspace, after package inspection and with a generated lockfile. Use `npm ci --ignore-scripts` with inherited proxy settings disabled, then typecheck, test, build, and run a local MCP stdio smoke test. Use a container, VM, or equivalent host sandbox when the project or dependency graph is untrusted.\n6. **Agent installation (optional).** After a verified project is generated, ask whether the user wants **project only** or **project + agent installation**. Project-only is the default. For installation, detect clients read-only, present the detected targets and exact config paths/command/args/cwd/env *names* plus backup paths, and require a separate final confirmation bound to the reviewed installation plan. Never read `.env`, copy secret values, silently replace a server name, or mutate an undetected/unsupported client; provide a portable `mcpServers.json` export instead.\n7. **Publication.** **Immediately before GitHub publication**, record owner/org, repository name, visibility, and source branch. Resolve the actual checked-out/ref-to-publish branch and stop unless it exactly equals the recorded source branch. Ask for explicit user confirmation before the publication action.\n\n## Optional agent installation workflow\n\nOnly use this after generated-project verification succeeds. Read-only discovery covers Hermes, Claude Code, Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode. This release has verified native config adapters for **Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode**, plus official CLI adapters for **Hermes** (`hermes mcp add` then `hermes mcp test`) and **Claude Code** (`claude mcp add --transport stdio` then `claude mcp list`). Hermes and Claude Code configuration files are never guessed or edited directly. If either CLI is missing or its add/verification action fails, the adapter removes a just-added server when possible and reports the target as failed; use portable export instead.\n\n```bash\n# 1. The assistant asks: \"프로젝트만 생성할까요, 아니면 생성 후 에이전트에 탑재할까요?\"\n# 2. For install, inspect and show a secret-free plan before any config write.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-plan \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\"\n\n# 3. Review the preview, then explicitly issue the plan-bound one-time confirmation.\nPLAN_DIGEST=\"...shown by install-plan...\"\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-approve --plan-digest \"$PLAN_DIGEST\"\n\n# 4. Apply only the unchanged approved plan. Native registration is fail-closed\n#    unless the selected client already has a detected regular config file. Each\n#    target gets a 0600 backup; a later target failure restores earlier targets,\n#    and every write is reread/parsed before success is reported.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-apply \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\" --confirm-plan-digest \"$PLAN_DIGEST\"\n```\n\nFor no-write portability, use `install-export --project \"$OUTPUT\"`; it writes only\n`$OUTPUT/agent-install/mcpServers.json`, never an agent configuration. Preview and\nreceipts expose `env_names` only—never `.env` content or credential values.\n\n## Runtime compatibility\n\nRead [references/type-mcp-runtime.md](references/type-mcp-runtime.md) before modifying generated TypeScript. The default generated standard ESM path uses the public ESM/NodeNext decorator import:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp\";\n```\n\nUse only `McpServer`, `McpTool`, `createMcpServer`, `startStdioServer`, `zod`, and an explicit `InstanceResolver` from the public contract. Legacy decorators are a separate, opt-in compatibility surface for CommonJS/Node16 projects that enable `experimentalDecorators`:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp/legacy\";\n```\n\nThese are distinct entrypoints with distinct decorator semantics. Do not change the generator templates to the legacy/CommonJS path; generated projects remain standard ESM consumers and never copy runtime source.\n\n## Verification checklist\n\n- [ ] Source is supplied explicitly; no origin crawling occurred.\n- [ ] Manifest is secret-free, evidence-backed, and canonically digested.\n- [ ] Digest approval and a valid single-use receipt precede generation.\n- [ ] Output target passed the empty/replace and traversal/symlink safety gates.\n- [ ] Protected writes are authorized before request construction.\n- [ ] Generated project uses the published `@theorvane/type-mcp@0.3.2` release line only and includes a reviewed `package-lock.json`; confirm registry provenance before changing this version.\n- [ ] Contained `npm ci --ignore-scripts`/typecheck/test/build/MCP smoke passes; external sandboxing is used for untrusted dependency installation.\n- [ ] Immediately before GitHub publication, user confirms owner/name/visibility/source branch and the resolved branch matches.\n\nFile v0.2.6:_meta.json\n\n{\n  \"ownerId\": \"kn701ftcm7pjm5537hh2jnv7y18b5q10\",\n  \"slug\": \"api-to-typemcp\",\n  \"version\": \"0.2.6\",\n  \"publishedAt\": 1786604975571\n}\n\nFile v0.2.6:references/agent-mcp-installation.md\n\n# Agent MCP Installation Reference\n\n**Status:** implementation contract\n**Retrieved:** 2026-07-28\n\n`api-to-typemcp` produces local stdio MCP projects. Project-only generation is the default. Only after contained generated-project verification may the skill offer agent installation. Detection is read-only; installation requires selected targets, a displayed secret-free plan, and a separate final confirmation.\n\n## Global safety contract\n\n- The installer never reads `.env`, resolves credentials, or writes secret values into an agent config, plan, log, backup, or portable export. It displays environment-variable names only.\n- `generate` never scans or edits agent configuration.\n- Unknown, malformed, symlinked, fingerprint-changed, or unsupported targets fail closed.\n- Portable export does not modify an agent configuration. It writes a secret-free standard `mcpServers` snippet under generated-project `agent-install/`.\n- Per-target failure never implies another target is installed; a changed target has a same-directory backup and target-local rollback.\n- Protected writes remain fail-closed under `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS`.\n\n## hermes\n\n**Official reference:** https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses only the documented `hermes mcp add <name> --command node --args <absolute-entry>` CLI path. The reviewed plan records the CLI-managed candidate path for operator visibility but the installer never reads or edits it directly. After registration, it runs `hermes mcp test <name>`; any non-zero result triggers `hermes mcp remove <name>` as compensating rollback. Hermes CLI currently exposes no cwd flag, so the generated absolute `dist/index.js` entrypoint is used and the plan reports the canonical project cwd for review. Environment variable values are never read or passed; users provide required values through their Hermes execution environment.\n\n## claude-code\n\n**Official reference:** https://docs.anthropic.com/en/docs/claude-code/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses the documented stdio form `claude mcp add --transport stdio <name> -- node <absolute-entry>`, where `--` separates Claude Code options from the server command. The installer never reads or edits Claude settings directly. It verifies registration using `claude mcp list` and requires the named server in successful output; a failed or absent discovery triggers `claude mcp remove <name>` as compensating rollback. Claude Code’s documented add form has no cwd argument, so the generated absolute entrypoint is used and the canonical project cwd remains plan-visible only. Environment variable values are never read or passed; users provide required values through their Claude Code execution environment.\n\n## codex\n\n**Official reference:** https://developers.openai.com/codex/cli/reference\n**Retrieved:** 2026-07-28\n\nPreferred path: `codex mcp add`, `codex mcp get`, and `codex mcp list`. Native entries use TOML `mcp_servers`. Without a safe CLI path, append only a missing validated table; reject existing target tables or syntax that cannot be preserved.\n\n## cursor\n\n**Official reference:** https://cursor.com/docs/mcp\n**Retrieved:** 2026-07-28\n\nCursor uses a selected user/workspace JSON `mcpServers` object in `mcp.json`. Direct mutation is only for valid non-symlink JSON with preservation guarantees; otherwise return portable export.\n\n**Verification:** reread/schema-check the exact target, then reload Cursor MCP configuration or restart and have the user confirm the named server appears. Do not call an upstream API tool.\n\n## vscode-copilot\n\n**Official reference:** https://code.visualstudio.com/docs/agent-customization/mcp-servers\n**Retrieved:** 2026-07-28\n\nVS Code/Copilot supports explicit workspace `.vscode/mcp.json` or user-profile MCP scope. Workspace credentials must not be hardcoded. Only valid non-symlink JSON with `mcpServers` can be changed.\n\n**Verification:** reread/schema-check the target, then use the MCP view/refresh flow and have the user confirm the server appears. Do not invoke a generated API tool.\n\n## gemini-cli\n\n**Official reference:** https://geminicli.com/docs/tools/mcp-server/\n**Retrieved:** 2026-07-28\n\nGemini CLI uses top-level `mcpServers` in explicit project or global `settings.json`. The plan records scope and no host/project secret values are read.\n\n**Verification:** reread/schema-check `settings.json`, restart Gemini CLI, and use its MCP inspection flow to confirm local discovery. Failed discovery rolls back this target only.\n\n## opencode\n\n**Official reference:** https://opencode.ai/docs/mcp-servers/\n**Retrieved:** 2026-07-28\n\nOpenCode supports local and remote MCP servers. `~/.config/opencode/opencode.json` is a **Linux/XDG example**, not a universal path. Native local servers are under `mcp.servers` with a command array. Prefer documented `opencode mcp add`; otherwise mutate only valid non-symlink JSON and fail closed if format differs.\n\n**Verification:** use OpenCode MCP server-management inspection after registration plus reread/schema-check of direct JSON writes. Confirm discovery without calling upstream tools.\n\n## Portable entry shape\n\n```json\n{\n  \"mcpServers\": {\n    \"example-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/generated-project/dist/index.js\"],\n      \"cwd\": \"/absolute/generated-project\"\n    }\n  }\n}\n```\n\nRequired environment variables are names only; users provide values outside generated artifacts and agent configuration.\n\nFile v0.2.6:references/type-mcp-runtime.md\n\n# TypeMCP Runtime Contract\n\nGenerated projects use the reviewed public npm package on the current 0.3.2 release line:\n\n```json\n\"@theorvane/type-mcp\": \"0.3.2\"\n```\n\n`@theorvane/type-mcp@0.3.2` is published with npm registry `gitHead` and GitHub Release `v0.3.2` both resolving to `e75bcf6a81ef4df57301b6154a0088845020886f`.\n\n## Allowed public API\n\nThe generator's default standard ESM path uses standard decorators from the public ESM/NodeNext entrypoint:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp\";\n```\n\nGenerated TypeScript uses only these public exports:\n\n- `@McpServer`\n- `@McpTool`\n- `createMcpServer`\n- `startStdioServer`\n- `zod`\n- an explicit `InstanceResolver`\n\n`createMcpServer` and `startStdioServer` are asynchronous and must be awaited. Standard decorators use TC39 semantics: generated `tsconfig.json` must not enable legacy `experimentalDecorators` or `emitDecoratorMetadata`.\n\n`@McpTool` requires an `input` Zod object. Generated code pins Zod v4 (`^4.4.3`) because that is the compatible public runtime contract for `@theorvane/type-mcp@0.3.2`.\n\n## Legacy decorator compatibility\n\nStandard and legacy decorators use distinct entrypoints and distinct decorator semantics. Legacy decorators are an opt-in public entrypoint for external CommonJS/Node16 projects that intentionally use TypeScript's legacy decorator mode; those projects must enable `experimentalDecorators` and import the decorators only from:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp/legacy\";\n```\n\nDo not mix this entrypoint with the standard ESM/NodeNext imports. The generator does not copy TypeMCP runtime source and must remain on its default standard ESM path; do not change its templates to legacy decorators or CommonJS.\n\n## Prohibited runtime boundaries\n\nNever generate or publish any of the following:\n\n- copied TypeMCP source code;\n- `file:`, `git:`, `link:`, or `portal:` dependencies;\n- imports from private, undocumented, or unavailable TypeMCP APIs;\n- local TypeMCP checkouts as a generated-project dependency.\n\nBefore generated lifecycle scripts run, contained verification inspects dependency metadata and the generated `package-lock.json`, then runs `npm ci --ignore-scripts` in a fresh isolated workspace with inherited npm proxy configuration disabled. It then typechecks, tests, builds, and executes a local stdio smoke test against a mock upstream. Use a host container/VM/sandbox when the dependency graph is untrusted.\n\nFile v0.2.6:skill-card.md\n\n## Description:\n\nUse when turning supplied API sources into a safe TypeMCP project.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[sjungwon03](https://clawhub.ai/user/sjungwon03)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineers use this skill to convert supplied local OpenAPI, Swagger UI, or Markdown/HTML API references into a reviewed TypeMCP stdio MCP project. It is intended for project generation first, with optional agent installation only after verification and explicit confirmation.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A replace-generation path can overwrite files outside the chosen output folder.\n\nMitigation: Generate into a newly created empty directory, avoid --replace on directories that were not created and inspected for this run, and review paths before generation.\n\nRisk: Agent installation can modify persistent MCP client configuration.\n\nMitigation: Prefer project-only generation, review the secret-free installation plan, and require explicit confirmation before applying any agent configuration changes.\n\nRisk: Generated project verification installs npm dependencies and may be untrusted.\n\nMitigation: Run npm verification in a container, VM, or equivalent host sandbox for untrusted inputs.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/sjungwon03/skills/api-to-typemcp)\n- [TypeMCP Runtime Contract](references/type-mcp-runtime.md)\n- [Agent MCP Installation Reference](references/agent-mcp-installation.md)\n- [Hermes MCP documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)\n- [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp)\n- [Codex CLI MCP reference](https://developers.openai.com/codex/cli/reference)\n- [Cursor MCP documentation](https://cursor.com/docs/mcp)\n- [VS Code MCP servers documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance plus generated TypeScript project files and JSON/TOML MCP configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Generated projects use a pinned TypeMCP runtime line and may include optional agent installation plans or portable MCP server exports.]\n\n## Skill Version(s):\n\n0.2.6 (source: server release metadata and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.2.6:tests/fixtures/api-reference.md\n\n# Petstore API Reference\n\n## Authentication\n\nAll requests require an `api_key` header.\n\n## Endpoints\n\n### List Pets\n\n    GET /pets\n\nReturns all pets.\n\n### Get Pet by ID\n\n    GET /pets/{petId}\n\nReturns a single pet.\n\n### Create Pet\n\n    POST /pets\n\nCreates a new pet. Request body:\n\n```json\n{\"name\": \"Buddy\", \"status\": \"available\"}\n```\n\n### Delete Pet\n\n    DELETE /pets/{petId}\n\nDeletes a pet by ID.\n\n## Notes\n\nThe API rate limit is 100 requests per minute.\nContact support@example.com for access issues.\n\nFile v0.2.6:tests/fixtures/petstore.openapi.json\n\n{\n  \"openapi\": \"3.0.3\",\n  \"info\": {\"title\": \"Pet store\", \"version\": \"1.0.0\"},\n  \"servers\": [{\"url\": \"https://api.example.test/v1?api_key=fixture-secret-query\"}],\n  \"paths\": {\n    \"/pets/{petId}\": {\n      \"get\": {\n        \"operationId\": \"getPet\",\n        \"parameters\": [\n          {\"name\": \"petId\", \"in\": \"path\", \"required\": true, \"schema\": {\"type\": \"string\"}},\n          {\"name\": \"api_key\", \"in\": \"query\", \"schema\": {\"type\": \"string\", \"default\": \"fixture-secret-query\"}}\n        ],\n        \"responses\": {\"200\": {\"description\": \"A pet\"}}\n      }\n    },\n    \"/pets\": {\n      \"post\": {\n        \"operationId\": \"createPet\",\n        \"requestBody\": {\"required\": true, \"content\": {\"application/json\": {\"schema\": {\"type\": \"object\"}}}},\n        \"responses\": {\"201\": {\"description\": \"Created\"}}\n      }\n    }\n  }\n}\n\nFile v0.2.6:tests/fixtures/petstore.swagger.yaml\n\nswagger: \"2.0\"\ninfo:\n  title: Pet store\n  version: \"1.0.0\"\nhost: api.example.test\nbasePath: /v1\nschemes:\n  - https\npaths:\n  /pets/{petId}:\n    get:\n      operationId: getPet\n      parameters:\n        - name: petId\n          in: path\n          required: true\n          type: string\n      responses:\n        \"200\":\n          description: A pet\n  /pets:\n    post:\n      operationId: createPet\n      parameters:\n        - name: body\n          in: body\n          required: true\n          schema:\n            type: object\n      responses:\n        \"201\":\n          description: Created\n\nFile v0.2.6:requirements.txt\n\n# Required by `scripts/intake.py` for safe local YAML parsing.\nPyYAML==6.0.3\n\nArchive v0.2.5: 52 files, 109023 bytes\n\nFiles: references/agent-mcp-installation.md (5525b), references/type-mcp-runtime.md (2463b), requirements.txt (77b), scripts/agent_clients.py (4854b), scripts/api_to_typemcp.py (15284b), scripts/approval.py (6293b), scripts/config_codecs.py (1631b), scripts/documents.py (3785b), scripts/install_mcp.py (15565b), scripts/install_plan.py (7585b), scripts/intake.py (7300b), scripts/manifest.py (762b), scripts/policy.py (1543b), scripts/render.py (16514b), scripts/structured_specs.py (16750b), scripts/swagger_ui.py (2075b), scripts/verify_generated.py (11452b), skill-card.md (2745b), SKILL.md (10011b), templates/typescript-stdio/package-lock.json.tmpl (87670b), templates/typescript-stdio/package.json.tmpl (463b), templates/typescript-stdio/README.md.tmpl (962b), templates/typescript-stdio/src/api-client.ts.tmpl (1751b), templates/typescript-stdio/src/index.ts.tmpl (255b), templates/typescript-stdio/src/policy.ts.tmpl (1665b), templates/typescript-stdio/tsconfig.json.tmpl (278b), tests/fixtures/api-reference.html (632b), tests/fixtures/api-reference.md (504b), tests/fixtures/mock_upstream.py (3915b), tests/fixtures/petstore.openapi.json (804b), tests/fixtures/petstore.swagger.yaml (579b), tests/fixtures/swagger-ui.html (434b), tests/test_agent_clients.py (3804b), tests/test_agent_installation_docs.py (1522b), tests/test_approval.py (6165b), tests/test_cli_agent_adapters.py (8177b), tests/test_config_codecs.py (1672b), tests/test_document_intake.py (4595b), tests/test_documents.py (6012b), tests/test_engine_cli.py (9325b), tests/test_generated_project_e2e.py (9879b), tests/test_generated_project_static.py (7946b), tests/test_install_mcp.py (6505b), tests/test_install_plan.py (6737b), tests/test_manifest.py (14717b), tests/test_output_safety.py (9128b), tests/test_policy.py (1512b), tests/test_render.py (10488b), tests/test_runtime_documentation.py (2455b), tests/test_swagger_ui.py (3218b), tests/test_verify_generated_security.py (3333b), _meta.json (133b)\n\nFile v0.2.5:SKILL.md\n\n---\nname: api-to-typemcp\ndescription: Use when turning supplied API sources into a safe TypeMCP project.\nversion: 0.2.5\ncategory: integration\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [mcp, api, openapi, swagger, code-generation, type-mcp]\n    related_skills: []\n  openclaw:\n    requires:\n      bins: [python3, node, npm]\n    envVars:\n      - name: TYPE_MCP_APPROVAL_STATE_DIR\n        required: false\n        description: Isolated directory for single-use generation approvals.\n      - name: TYPE_MCP_BASE_URL\n        required: false\n        description: Local test upstream used only by contained verification.\n---\n\n# API to TypeMCP\n\n## Overview\n\nThis released skill is a complete, bundled generator delivery unit. Its **bundled skill engine** is in `scripts/`, its controlled TypeScript output templates are in `templates/`, and its public TypeMCP runtime constraints are in [references/type-mcp-runtime.md](references/type-mcp-runtime.md).\n\nGenerated projects use the current published `@theorvane/type-mcp@0.3.2` release line and only its public package exports; they never copy TypeMCP source or use local, `file:`, `git:`, `link:`, or private runtime APIs. The npm registry `gitHead` and GitHub Release `v0.3.2` both resolve to `e75bcf6a81ef4df57301b6154a0088845020886f`.\n\n## When to use\n\nUse this skill with a **supplied local** OpenAPI 3.x / Swagger 2.0 JSON/YAML file, supplied Swagger UI HTML, or supplied Markdown/HTML API reference. Do not use it to crawl a bare origin, infer undocumented operations, make mutating calls by default, or publish without explicit final confirmation.\n\n## Execution permissions and containment boundary\n\nThe engine reads only the user-supplied source and files bundled with this skill. It writes only the caller-created output directory and the optional `TYPE_MCP_APPROVAL_STATE_DIR`; it never modifies an upstream API or publishes a repository without the separate explicit gates below.\n\nThe engine invokes `python3`. Optional generated-project verification additionally invokes `npm` and `node`, uses a fresh temporary workspace, passes a credential-scrubbed environment, disables inherited npm proxy settings and lifecycle scripts, and installs exactly the generated `package-lock.json` graph with `npm ci`. That install requires outbound access to the npm registry; the generator itself performs no network fetch or crawling, and the smoke test targets only a caller-provided local test upstream.\n\nThis verifier is **process containment**, not a claim of kernel or network isolation. Run it in a container, VM, or an equivalent host sandbox when the generated project or its dependency installation is untrusted.\n\n## Bundled engine workflow\n\nRun the engine through its installed skill-relative path. Set `SKILL_DIR` to the directory containing this `SKILL.md`; create a **controlled temporary output directory** yourself and keep it empty.\n\n```bash\nSKILL_DIR=\"/absolute/path/to/api-to-typemcp\"\nSOURCE=\"/absolute/path/to/supplied-openapi.json\"\nOUTPUT=\"$(mktemp -d -t api-to-typemcp-output.XXXXXX)\"\nSTATE=\"$(mktemp -d -t api-to-typemcp-state.XXXXXX)\"\nexport TYPE_MCP_APPROVAL_STATE_DIR=\"$STATE\"\n\n# 1. Inspect and build the exact secret-free manifest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" inspect --file \"$SOURCE\" --json\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest --file \"$SOURCE\" --json > manifest.json\nDIGEST=\"$(python3 -c 'import json; print(json.load(open(\"manifest.json\"))[\"digest\"])')\"\n\n# 2. Review the manifest, then explicitly approve precisely that digest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" approve \\\n  --file \"$SOURCE\" --manifest-digest \"$DIGEST\"\n\n# 3. Render only after approval, with an exact digest confirmation.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" generate \\\n  --file \"$SOURCE\" --output \"$OUTPUT\" \\\n  --confirm-manifest-digest \"$DIGEST\"\n```\n\nFor supplied Markdown or HTML, add an explicit origin; no page is fetched or crawled:\n\n```bash\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest \\\n  --file \"/absolute/path/to/reference.md\" \\\n  --base-url \"https://api.example.test\" --json\n```\n\nSwagger UI discovery is performed by `inspect` in-memory and returns only an explicit configured spec reference. The user must separately supply that structured spec; do not fetch it automatically.\n\n## Mandatory safety gates\n\n1. **Manifest first.** Treat every source as untrusted. Review canonical secret-free manifest data before generation.\n2. **Receipt gate.** `approve` issues a HMAC-protected, digest-bound, single-use receipt. A changed, expired, tampered, or already-consumed receipt stops `generate`.\n3. **Output gate.** The output directory must already exist and be empty unless `--replace` is explicitly supplied. Symlinks and `..` traversal are rejected.\n4. **Runtime policy.** `GET`/`HEAD`/`OPTIONS` are read operations. `POST`/`PUT`/`PATCH`/`DELETE` are protected writes and require exact known IDs in `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS` **before URL, query, headers, body, authentication, or dispatch**. Unknown methods deny.\n5. **Containment.** Verify generated projects in a scrubbed temporary workspace, after package inspection and with a generated lockfile. Use `npm ci --ignore-scripts` with inherited proxy settings disabled, then typecheck, test, build, and run a local MCP stdio smoke test. Use a container, VM, or equivalent host sandbox when the project or dependency graph is untrusted.\n6. **Agent installation (optional).** After a verified project is generated, ask whether the user wants **project only** or **project + agent installation**. Project-only is the default. For installation, detect clients read-only, present the detected targets and exact config paths/command/args/cwd/env *names* plus backup paths, and require a separate final confirmation bound to the reviewed installation plan. Never read `.env`, copy secret values, silently replace a server name, or mutate an undetected/unsupported client; provide a portable `mcpServers.json` export instead.\n7. **Publication.** **Immediately before GitHub publication**, record owner/org, repository name, visibility, and source branch. Resolve the actual checked-out/ref-to-publish branch and stop unless it exactly equals the recorded source branch. Ask for explicit user confirmation before the publication action.\n\n## Optional agent installation workflow\n\nOnly use this after generated-project verification succeeds. Read-only discovery covers Hermes, Claude Code, Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode. This release has verified native config adapters for **Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode**, plus official CLI adapters for **Hermes** (`hermes mcp add` then `hermes mcp test`) and **Claude Code** (`claude mcp add --transport stdio` then `claude mcp list`). Hermes and Claude Code configuration files are never guessed or edited directly. If either CLI is missing or its add/verification action fails, the adapter removes a just-added server when possible and reports the target as failed; use portable export instead.\n\n```bash\n# 1. The assistant asks: \"프로젝트만 생성할까요, 아니면 생성 후 에이전트에 탑재할까요?\"\n# 2. For install, inspect and show a secret-free plan before any config write.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-plan \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\"\n\n# 3. Review the preview, then explicitly issue the plan-bound one-time confirmation.\nPLAN_DIGEST=\"...shown by install-plan...\"\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-approve --plan-digest \"$PLAN_DIGEST\"\n\n# 4. Apply only the unchanged approved plan. Native registration is fail-closed\n#    unless the selected client already has a detected regular config file. Each\n#    target gets a 0600 backup; a later target failure restores earlier targets,\n#    and every write is reread/parsed before success is reported.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-apply \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\" --confirm-plan-digest \"$PLAN_DIGEST\"\n```\n\nFor no-write portability, use `install-export --project \"$OUTPUT\"`; it writes only\n`$OUTPUT/agent-install/mcpServers.json`, never an agent configuration. Preview and\nreceipts expose `env_names` only—never `.env` content or credential values.\n\n## Runtime compatibility\n\nRead [references/type-mcp-runtime.md](references/type-mcp-runtime.md) before modifying generated TypeScript. The default generated standard ESM path uses the public ESM/NodeNext decorator import:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp\";\n```\n\nUse only `McpServer`, `McpTool`, `createMcpServer`, `startStdioServer`, `zod`, and an explicit `InstanceResolver` from the public contract. Legacy decorators are a separate, opt-in compatibility surface for CommonJS/Node16 projects that enable `experimentalDecorators`:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp/legacy\";\n```\n\nThese are distinct entrypoints with distinct decorator semantics. Do not change the generator templates to the legacy/CommonJS path; generated projects remain standard ESM consumers and never copy runtime source.\n\n## Verification checklist\n\n- [ ] Source is supplied explicitly; no origin crawling occurred.\n- [ ] Manifest is secret-free, evidence-backed, and canonically digested.\n- [ ] Digest approval and a valid single-use receipt precede generation.\n- [ ] Output target passed the empty/replace and traversal/symlink safety gates.\n- [ ] Protected writes are authorized before request construction.\n- [ ] Generated project uses the published `@theorvane/type-mcp@0.3.2` release line only and includes a reviewed `package-lock.json`; confirm registry provenance before changing this version.\n- [ ] Contained `npm ci --ignore-scripts`/typecheck/test/build/MCP smoke passes; external sandboxing is used for untrusted dependency installation.\n- [ ] Immediately before GitHub publication, user confirms owner/name/visibility/source branch and the resolved branch matches.\n\nFile v0.2.5:_meta.json\n\n{\n  \"ownerId\": \"kn701ftcm7pjm5537hh2jnv7y18b5q10\",\n  \"slug\": \"api-to-typemcp\",\n  \"version\": \"0.2.5\",\n  \"publishedAt\": 1786602808794\n}\n\nFile v0.2.5:references/agent-mcp-installation.md\n\n# Agent MCP Installation Reference\n\n**Status:** implementation contract\n**Retrieved:** 2026-07-28\n\n`api-to-typemcp` produces local stdio MCP projects. Project-only generation is the default. Only after contained generated-project verification may the skill offer agent installation. Detection is read-only; installation requires selected targets, a displayed secret-free plan, and a separate final confirmation.\n\n## Global safety contract\n\n- The installer never reads `.env`, resolves credentials, or writes secret values into an agent config, plan, log, backup, or portable export. It displays environment-variable names only.\n- `generate` never scans or edits agent configuration.\n- Unknown, malformed, symlinked, fingerprint-changed, or unsupported targets fail closed.\n- Portable export does not modify an agent configuration. It writes a secret-free standard `mcpServers` snippet under generated-project `agent-install/`.\n- Per-target failure never implies another target is installed; a changed target has a same-directory backup and target-local rollback.\n- Protected writes remain fail-closed under `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS`.\n\n## hermes\n\n**Official reference:** https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses only the documented `hermes mcp add <name> --command node --args <absolute-entry>` CLI path. The reviewed plan records the CLI-managed candidate path for operator visibility but the installer never reads or edits it directly. After registration, it runs `hermes mcp test <name>`; any non-zero result triggers `hermes mcp remove <name>` as compensating rollback. Hermes CLI currently exposes no cwd flag, so the generated absolute `dist/index.js` entrypoint is used and the plan reports the canonical project cwd for review. Environment variable values are never read or passed; users provide required values through their Hermes execution environment.\n\n## claude-code\n\n**Official reference:** https://docs.anthropic.com/en/docs/claude-code/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses the documented stdio form `claude mcp add --transport stdio <name> -- node <absolute-entry>`, where `--` separates Claude Code options from the server command. The installer never reads or edits Claude settings directly. It verifies registration using `claude mcp list` and requires the named server in successful output; a failed or absent discovery triggers `claude mcp remove <name>` as compensating rollback. Claude Code’s documented add form has no cwd argument, so the generated absolute entrypoint is used and the canonical project cwd remains plan-visible only. Environment variable values are never read or passed; users provide required values through their Claude Code execution environment.\n\n## codex\n\n**Official reference:** https://developers.openai.com/codex/cli/reference\n**Retrieved:** 2026-07-28\n\nPreferred path: `codex mcp add`, `codex mcp get`, and `codex mcp list`. Native entries use TOML `mcp_servers`. Without a safe CLI path, append only a missing validated table; reject existing target tables or syntax that cannot be preserved.\n\n## cursor\n\n**Official reference:** https://cursor.com/docs/mcp\n**Retrieved:** 2026-07-28\n\nCursor uses a selected user/workspace JSON `mcpServers` object in `mcp.json`. Direct mutation is only for valid non-symlink JSON with preservation guarantees; otherwise return portable export.\n\n**Verification:** reread/schema-check the exact target, then reload Cursor MCP configuration or restart and have the user confirm the named server appears. Do not call an upstream API tool.\n\n## vscode-copilot\n\n**Official reference:** https://code.visualstudio.com/docs/agent-customization/mcp-servers\n**Retrieved:** 2026-07-28\n\nVS Code/Copilot supports explicit workspace `.vscode/mcp.json` or user-profile MCP scope. Workspace credentials must not be hardcoded. Only valid non-symlink JSON with `mcpServers` can be changed.\n\n**Verification:** reread/schema-check the target, then use the MCP view/refresh flow and have the user confirm the server appears. Do not invoke a generated API tool.\n\n## gemini-cli\n\n**Official reference:** https://geminicli.com/docs/tools/mcp-server/\n**Retrieved:** 2026-07-28\n\nGemini CLI uses top-level `mcpServers` in explicit project or global `settings.json`. The plan records scope and no host/project secret values are read.\n\n**Verification:** reread/schema-check `settings.json`, restart Gemini CLI, and use its MCP inspection flow to confirm local discovery. Failed discovery rolls back this target only.\n\n## opencode\n\n**Official reference:** https://opencode.ai/docs/mcp-servers/\n**Retrieved:** 2026-07-28\n\nOpenCode supports local and remote MCP servers. `~/.config/opencode/opencode.json` is a **Linux/XDG example**, not a universal path. Native local servers are under `mcp.servers` with a command array. Prefer documented `opencode mcp add`; otherwise mutate only valid non-symlink JSON and fail closed if format differs.\n\n**Verification:** use OpenCode MCP server-management inspection after registration plus reread/schema-check of direct JSON writes. Confirm discovery without calling upstream tools.\n\n## Portable entry shape\n\n```json\n{\n  \"mcpServers\": {\n    \"example-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/generated-project/dist/index.js\"],\n      \"cwd\": \"/absolute/generated-project\"\n    }\n  }\n}\n```\n\nRequired environment variables are names only; users provide values outside generated artifacts and agent configuration.\n\nFile v0.2.5:references/type-mcp-runtime.md\n\n# TypeMCP Runtime Contract\n\nGenerated projects use the reviewed public npm package on the current 0.3.2 release line:\n\n```json\n\"@theorvane/type-mcp\": \"0.3.2\"\n```\n\n`@theorvane/type-mcp@0.3.2` is published with npm registry `gitHead` and GitHub Release `v0.3.2` both resolving to `e75bcf6a81ef4df57301b6154a0088845020886f`.\n\n## Allowed public API\n\nThe generator's default standard ESM path uses standard decorators from the public ESM/NodeNext entrypoint:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp\";\n```\n\nGenerated TypeScript uses only these public exports:\n\n- `@McpServer`\n- `@McpTool`\n- `createMcpServer`\n- `startStdioServer`\n- `zod`\n- an explicit `InstanceResolver`\n\n`createMcpServer` and `startStdioServer` are asynchronous and must be awaited. Standard decorators use TC39 semantics: generated `tsconfig.json` must not enable legacy `experimentalDecorators` or `emitDecoratorMetadata`.\n\n`@McpTool` requires an `input` Zod object. Generated code pins Zod v4 (`^4.4.3`) because that is the compatible public runtime contract for `@theorvane/type-mcp@0.3.2`.\n\n## Legacy decorator compatibility\n\nStandard and legacy decorators use distinct entrypoints and distinct decorator semantics. Legacy decorators are an opt-in public entrypoint for external CommonJS/Node16 projects that intentionally use TypeScript's legacy decorator mode; those projects must enable `experimentalDecorators` and import the decorators only from:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp/legacy\";\n```\n\nDo not mix this entrypoint with the standard ESM/NodeNext imports. The generator does not copy TypeMCP runtime source and must remain on its default standard ESM path; do not change its templates to legacy decorators or CommonJS.\n\n## Prohibited runtime boundaries\n\nNever generate or publish any of the following:\n\n- copied TypeMCP source code;\n- `file:`, `git:`, `link:`, or `portal:` dependencies;\n- imports from private, undocumented, or unavailable TypeMCP APIs;\n- local TypeMCP checkouts as a generated-project dependency.\n\nBefore generated lifecycle scripts run, contained verification inspects dependency metadata and the generated `package-lock.json`, then runs `npm ci --ignore-scripts` in a fresh isolated workspace with inherited npm proxy configuration disabled. It then typechecks, tests, builds, and executes a local stdio smoke test against a mock upstream. Use a host container/VM/sandbox when the dependency graph is untrusted.\n\nFile v0.2.5:skill-card.md\n\n## Description:\n\nUse when turning supplied API sources into a safe TypeMCP project.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[sjungwon03](https://clawhub.ai/user/sjungwon03)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineers use this skill to convert explicitly supplied OpenAPI, Swagger, Markdown, or HTML API sources into reviewed TypeScript stdio MCP projects. It supports manifest review, digest-bound approval, contained verification, and optional agent installation after separate confirmation.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Optional agent-configuration changes can modify local client settings.\n\nMitigation: Use project-only generation by default and run install-apply only after reviewing exact target config paths, backups, command, args, cwd, and environment variable names.\n\nRisk: Generated dependency artifacts and TypeMCP version evidence need human review before installation.\n\nMitigation: Verify the missing .env.example template and TypeMCP version mismatch, review the generated lockfile before npm install, and run verification in a sandbox for untrusted inputs.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/sjungwon03/skills/api-to-typemcp)\n- [TypeMCP Runtime Contract](references/type-mcp-runtime.md)\n- [Agent MCP Installation Reference](references/agent-mcp-installation.md)\n- [Hermes MCP documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)\n- [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp)\n- [Codex CLI MCP reference](https://developers.openai.com/codex/cli/reference)\n- [Cursor MCP documentation](https://cursor.com/docs/mcp)\n- [VS Code MCP servers documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)\n- [Gemini CLI MCP server documentation](https://geminicli.com/docs/tools/mcp-server/)\n- [OpenCode MCP servers documentation](https://opencode.ai/docs/mcp-servers/)\n\n## Skill Output:\n\n**Output Type(s):** [code, configuration, shell commands, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and generated TypeScript/JSON project files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Project-only generation is the default; optional agent installation requires separate review and confirmation.]\n\n## Skill Version(s):\n\n0.2.5 (source: server release metadata and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.2.5:tests/fixtures/api-reference.md\n\n# Petstore API Reference\n\n## Authentication\n\nAll requests require an `api_key` header.\n\n## Endpoints\n\n### List Pets\n\n    GET /pets\n\nReturns all pets.\n\n### Get Pet by ID\n\n    GET /pets/{petId}\n\nReturns a single pet.\n\n### Create Pet\n\n    POST /pets\n\nCreates a new pet. Request body:\n\n```json\n{\"name\": \"Buddy\", \"status\": \"available\"}\n```\n\n### Delete Pet\n\n    DELETE /pets/{petId}\n\nDeletes a pet by ID.\n\n## Notes\n\nThe API rate limit is 100 requests per minute.\nContact support@example.com for access issues.\n\nFile v0.2.5:tests/fixtures/petstore.openapi.json\n\n{\n  \"openapi\": \"3.0.3\",\n  \"info\": {\"title\": \"Pet store\", \"version\": \"1.0.0\"},\n  \"servers\": [{\"url\": \"https://api.example.test/v1?api_key=fixture-secret-query\"}],\n  \"paths\": {\n    \"/pets/{petId}\": {\n      \"get\": {\n        \"operationId\": \"getPet\",\n        \"parameters\": [\n          {\"name\": \"petId\", \"in\": \"path\", \"required\": true, \"schema\": {\"type\": \"string\"}},\n          {\"name\": \"api_key\", \"in\": \"query\", \"schema\": {\"type\": \"string\", \"default\": \"fixture-secret-query\"}}\n        ],\n        \"responses\": {\"200\": {\"description\": \"A pet\"}}\n      }\n    },\n    \"/pets\": {\n      \"post\": {\n        \"operationId\": \"createPet\",\n        \"requestBody\": {\"required\": true, \"content\": {\"application/json\": {\"schema\": {\"type\": \"object\"}}}},\n        \"responses\": {\"201\": {\"description\": \"Created\"}}\n      }\n    }\n  }\n}\n\nFile v0.2.5:tests/fixtures/petstore.swagger.yaml\n\nswagger: \"2.0\"\ninfo:\n  title: Pet store\n  version: \"1.0.0\"\nhost: api.example.test\nbasePath: /v1\nschemes:\n  - https\npaths:\n  /pets/{petId}:\n    get:\n      operationId: getPet\n      parameters:\n        - name: petId\n          in: path\n          required: true\n          type: string\n      responses:\n        \"200\":\n          description: A pet\n  /pets:\n    post:\n      operationId: createPet\n      parameters:\n        - name: body\n          in: body\n          required: true\n          schema:\n            type: object\n      responses:\n        \"201\":\n          description: Created\n\nFile v0.2.5:requirements.txt\n\n# Required by `scripts/intake.py` for safe local YAML parsing.\nPyYAML==6.0.3\n\nArchive v0.2.4: 52 files, 109157 bytes\n\nFiles: references/agent-mcp-installation.md (5525b), references/type-mcp-runtime.md (2463b), requirements.txt (77b), scripts/agent_clients.py (4854b), scripts/api_to_typemcp.py (15284b), scripts/approval.py (6293b), scripts/config_codecs.py (1631b), scripts/documents.py (3785b), scripts/install_mcp.py (15565b), scripts/install_plan.py (7585b), scripts/intake.py (7300b), scripts/manifest.py (762b), scripts/policy.py (1543b), scripts/render.py (16514b), scripts/structured_specs.py (16750b), scripts/swagger_ui.py (2075b), scripts/verify_generated.py (11452b), skill-card.md (3185b), SKILL.md (10011b), templates/typescript-stdio/package-lock.json.tmpl (87670b), templates/typescript-stdio/package.json.tmpl (463b), templates/typescript-stdio/README.md.tmpl (962b), templates/typescript-stdio/src/api-client.ts.tmpl (1751b), templates/typescript-stdio/src/index.ts.tmpl (255b), templates/typescript-stdio/src/policy.ts.tmpl (1665b), templates/typescript-stdio/tsconfig.json.tmpl (278b), tests/fixtures/api-reference.html (632b), tests/fixtures/api-reference.md (504b), tests/fixtures/mock_upstream.py (3915b), tests/fixtures/petstore.openapi.json (804b), tests/fixtures/petstore.swagger.yaml (579b), tests/fixtures/swagger-ui.html (434b), tests/test_agent_clients.py (3804b), tests/test_agent_installation_docs.py (1522b), tests/test_approval.py (6165b), tests/test_cli_agent_adapters.py (8177b), tests/test_config_codecs.py (1672b), tests/test_document_intake.py (4595b), tests/test_documents.py (6012b), tests/test_engine_cli.py (9325b), tests/test_generated_project_e2e.py (9879b), tests/test_generated_project_static.py (7946b), tests/test_install_mcp.py (6505b), tests/test_install_plan.py (6737b), tests/test_manifest.py (14717b), tests/test_output_safety.py (9128b), tests/test_policy.py (1512b), tests/test_render.py (10488b), tests/test_runtime_documentation.py (2455b), tests/test_swagger_ui.py (3218b), tests/test_verify_generated_security.py (3333b), _meta.json (133b)\n\nFile v0.2.4:SKILL.md\n\n---\nname: api-to-typemcp\ndescription: Use when turning supplied API sources into a safe TypeMCP project.\nversion: 0.2.4\ncategory: integration\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [mcp, api, openapi, swagger, code-generation, type-mcp]\n    related_skills: []\n  openclaw:\n    requires:\n      bins: [python3, node, npm]\n    envVars:\n      - name: TYPE_MCP_APPROVAL_STATE_DIR\n        required: false\n        description: Isolated directory for single-use generation approvals.\n      - name: TYPE_MCP_BASE_URL\n        required: false\n        description: Local test upstream used only by contained verification.\n---\n\n# API to TypeMCP\n\n## Overview\n\nThis released skill is a complete, bundled generator delivery unit. Its **bundled skill engine** is in `scripts/`, its controlled TypeScript output templates are in `templates/`, and its public TypeMCP runtime constraints are in [references/type-mcp-runtime.md](references/type-mcp-runtime.md).\n\nGenerated projects use the current published `@theorvane/type-mcp@0.3.2` release line and only its public package exports; they never copy TypeMCP source or use local, `file:`, `git:`, `link:`, or private runtime APIs. The npm registry `gitHead` and GitHub Release `v0.3.2` both resolve to `e75bcf6a81ef4df57301b6154a0088845020886f`.\n\n## When to use\n\nUse this skill with a **supplied local** OpenAPI 3.x / Swagger 2.0 JSON/YAML file, supplied Swagger UI HTML, or supplied Markdown/HTML API reference. Do not use it to crawl a bare origin, infer undocumented operations, make mutating calls by default, or publish without explicit final confirmation.\n\n## Execution permissions and containment boundary\n\nThe engine reads only the user-supplied source and files bundled with this skill. It writes only the caller-created output directory and the optional `TYPE_MCP_APPROVAL_STATE_DIR`; it never modifies an upstream API or publishes a repository without the separate explicit gates below.\n\nThe engine invokes `python3`. Optional generated-project verification additionally invokes `npm` and `node`, uses a fresh temporary workspace, passes a credential-scrubbed environment, disables inherited npm proxy settings and lifecycle scripts, and installs exactly the generated `package-lock.json` graph with `npm ci`. That install requires outbound access to the npm registry; the generator itself performs no network fetch or crawling, and the smoke test targets only a caller-provided local test upstream.\n\nThis verifier is **process containment**, not a claim of kernel or network isolation. Run it in a container, VM, or an equivalent host sandbox when the generated project or its dependency installation is untrusted.\n\n## Bundled engine workflow\n\nRun the engine through its installed skill-relative path. Set `SKILL_DIR` to the directory containing this `SKILL.md`; create a **controlled temporary output directory** yourself and keep it empty.\n\n```bash\nSKILL_DIR=\"/absolute/path/to/api-to-typemcp\"\nSOURCE=\"/absolute/path/to/supplied-openapi.json\"\nOUTPUT=\"$(mktemp -d -t api-to-typemcp-output.XXXXXX)\"\nSTATE=\"$(mktemp -d -t api-to-typemcp-state.XXXXXX)\"\nexport TYPE_MCP_APPROVAL_STATE_DIR=\"$STATE\"\n\n# 1. Inspect and build the exact secret-free manifest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" inspect --file \"$SOURCE\" --json\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest --file \"$SOURCE\" --json > manifest.json\nDIGEST=\"$(python3 -c 'import json; print(json.load(open(\"manifest.json\"))[\"digest\"])')\"\n\n# 2. Review the manifest, then explicitly approve precisely that digest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" approve \\\n  --file \"$SOURCE\" --manifest-digest \"$DIGEST\"\n\n# 3. Render only after approval, with an exact digest confirmation.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" generate \\\n  --file \"$SOURCE\" --output \"$OUTPUT\" \\\n  --confirm-manifest-digest \"$DIGEST\"\n```\n\nFor supplied Markdown or HTML, add an explicit origin; no page is fetched or crawled:\n\n```bash\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest \\\n  --file \"/absolute/path/to/reference.md\" \\\n  --base-url \"https://api.example.test\" --json\n```\n\nSwagger UI discovery is performed by `inspect` in-memory and returns only an explicit configured spec reference. The user must separately supply that structured spec; do not fetch it automatically.\n\n## Mandatory safety gates\n\n1. **Manifest first.** Treat every source as untrusted. Review canonical secret-free manifest data before generation.\n2. **Receipt gate.** `approve` issues a HMAC-protected, digest-bound, single-use receipt. A changed, expired, tampered, or already-consumed receipt stops `generate`.\n3. **Output gate.** The output directory must already exist and be empty unless `--replace` is explicitly supplied. Symlinks and `..` traversal are rejected.\n4. **Runtime policy.** `GET`/`HEAD`/`OPTIONS` are read operations. `POST`/`PUT`/`PATCH`/`DELETE` are protected writes and require exact known IDs in `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS` **before URL, query, headers, body, authentication, or dispatch**. Unknown methods deny.\n5. **Containment.** Verify generated projects in a scrubbed temporary workspace, after package inspection and with a generated lockfile. Use `npm ci --ignore-scripts` with inherited proxy settings disabled, then typecheck, test, build, and run a local MCP stdio smoke test. Use a container, VM, or equivalent host sandbox when the project or dependency graph is untrusted.\n6. **Agent installation (optional).** After a verified project is generated, ask whether the user wants **project only** or **project + agent installation**. Project-only is the default. For installation, detect clients read-only, present the detected targets and exact config paths/command/args/cwd/env *names* plus backup paths, and require a separate final confirmation bound to the reviewed installation plan. Never read `.env`, copy secret values, silently replace a server name, or mutate an undetected/unsupported client; provide a portable `mcpServers.json` export instead.\n7. **Publication.** **Immediately before GitHub publication**, record owner/org, repository name, visibility, and source branch. Resolve the actual checked-out/ref-to-publish branch and stop unless it exactly equals the recorded source branch. Ask for explicit user confirmation before the publication action.\n\n## Optional agent installation workflow\n\nOnly use this after generated-project verification succeeds. Read-only discovery covers Hermes, Claude Code, Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode. This release has verified native config adapters for **Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode**, plus official CLI adapters for **Hermes** (`hermes mcp add` then `hermes mcp test`) and **Claude Code** (`claude mcp add --transport stdio` then `claude mcp list`). Hermes and Claude Code configuration files are never guessed or edited directly. If either CLI is missing or its add/verification action fails, the adapter removes a just-added server when possible and reports the target as failed; use portable export instead.\n\n```bash\n# 1. The assistant asks: \"프로젝트만 생성할까요, 아니면 생성 후 에이전트에 탑재할까요?\"\n# 2. For install, inspect and show a secret-free plan before any config write.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-plan \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\"\n\n# 3. Review the preview, then explicitly issue the plan-bound one-time confirmation.\nPLAN_DIGEST=\"...shown by install-plan...\"\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-approve --plan-digest \"$PLAN_DIGEST\"\n\n# 4. Apply only the unchanged approved plan. Native registration is fail-closed\n#    unless the selected client already has a detected regular config file. Each\n#    target gets a 0600 backup; a later target failure restores earlier targets,\n#    and every write is reread/parsed before success is reported.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-apply \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\" --confirm-plan-digest \"$PLAN_DIGEST\"\n```\n\nFor no-write portability, use `install-export --project \"$OUTPUT\"`; it writes only\n`$OUTPUT/agent-install/mcpServers.json`, never an agent configuration. Preview and\nreceipts expose `env_names` only—never `.env` content or credential values.\n\n## Runtime compatibility\n\nRead [references/type-mcp-runtime.md](references/type-mcp-runtime.md) before modifying generated TypeScript. The default generated standard ESM path uses the public ESM/NodeNext decorator import:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp\";\n```\n\nUse only `McpServer`, `McpTool`, `createMcpServer`, `startStdioServer`, `zod`, and an explicit `InstanceResolver` from the public contract. Legacy decorators are a separate, opt-in compatibility surface for CommonJS/Node16 projects that enable `experimentalDecorators`:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp/legacy\";\n```\n\nThese are distinct entrypoints with distinct decorator semantics. Do not change the generator templates to the legacy/CommonJS path; generated projects remain standard ESM consumers and never copy runtime source.\n\n## Verification checklist\n\n- [ ] Source is supplied explicitly; no origin crawling occurred.\n- [ ] Manifest is secret-free, evidence-backed, and canonically digested.\n- [ ] Digest approval and a valid single-use receipt precede generation.\n- [ ] Output target passed the empty/replace and traversal/symlink safety gates.\n- [ ] Protected writes are authorized before request construction.\n- [ ] Generated project uses the published `@theorvane/type-mcp@0.3.2` release line only and includes a reviewed `package-lock.json`; confirm registry provenance before changing this version.\n- [ ] Contained `npm ci --ignore-scripts`/typecheck/test/build/MCP smoke passes; external sandboxing is used for untrusted dependency installation.\n- [ ] Immediately before GitHub publication, user confirms owner/name/visibility/source branch and the resolved branch matches.\n\nFile v0.2.4:_meta.json\n\n{\n  \"ownerId\": \"kn701ftcm7pjm5537hh2jnv7y18b5q10\",\n  \"slug\": \"api-to-typemcp\",\n  \"version\": \"0.2.4\",\n  \"publishedAt\": 1786585105325\n}\n\nFile v0.2.4:references/agent-mcp-installation.md\n\n# Agent MCP Installation Reference\n\n**Status:** implementation contract\n**Retrieved:** 2026-07-28\n\n`api-to-typemcp` produces local stdio MCP projects. Project-only generation is the default. Only after contained generated-project verification may the skill offer agent installation. Detection is read-only; installation requires selected targets, a displayed secret-free plan, and a separate final confirmation.\n\n## Global safety contract\n\n- The installer never reads `.env`, resolves credentials, or writes secret values into an agent config, plan, log, backup, or portable export. It displays environment-variable names only.\n- `generate` never scans or edits agent configuration.\n- Unknown, malformed, symlinked, fingerprint-changed, or unsupported targets fail closed.\n- Portable export does not modify an agent configuration. It writes a secret-free standard `mcpServers` snippet under generated-project `agent-install/`.\n- Per-target failure never implies another target is installed; a changed target has a same-directory backup and target-local rollback.\n- Protected writes remain fail-closed under `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS`.\n\n## hermes\n\n**Official reference:** https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses only the documented `hermes mcp add <name> --command node --args <absolute-entry>` CLI path. The reviewed plan records the CLI-managed candidate path for operator visibility but the installer never reads or edits it directly. After registration, it runs `hermes mcp test <name>`; any non-zero result triggers `hermes mcp remove <name>` as compensating rollback. Hermes CLI currently exposes no cwd flag, so the generated absolute `dist/index.js` entrypoint is used and the plan reports the canonical project cwd for review. Environment variable values are never read or passed; users provide required values through their Hermes execution environment.\n\n## claude-code\n\n**Official reference:** https://docs.anthropic.com/en/docs/claude-code/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses the documented stdio form `claude mcp add --transport stdio <name> -- node <absolute-entry>`, where `--` separates Claude Code options from the server command. The installer never reads or edits Claude settings directly. It verifies registration using `claude mcp list` and requires the named server in successful output; a failed or absent discovery triggers `claude mcp remove <name>` as compensating rollback. Claude Code’s documented add form has no cwd argument, so the generated absolute entrypoint is used and the canonical project cwd remains plan-visible only. Environment variable values are never read or passed; users provide required values through their Claude Code execution environment.\n\n## codex\n\n**Official reference:** https://developers.openai.com/codex/cli/reference\n**Retrieved:** 2026-07-28\n\nPreferred path: `codex mcp add`, `codex mcp get`, and `codex mcp list`. Native entries use TOML `mcp_servers`. Without a safe CLI path, append only a missing validated table; reject existing target tables or syntax that cannot be preserved.\n\n## cursor\n\n**Official reference:** https://cursor.com/docs/mcp\n**Retrieved:** 2026-07-28\n\nCursor uses a selected user/workspace JSON `mcpServers` object in `mcp.json`. Direct mutation is only for valid non-symlink JSON with preservation guarantees; otherwise return portable export.\n\n**Verification:** reread/schema-check the exact target, then reload Cursor MCP configuration or restart and have the user confirm the named server appears. Do not call an upstream API tool.\n\n## vscode-copilot\n\n**Official reference:** https://code.visualstudio.com/docs/agent-customization/mcp-servers\n**Retrieved:** 2026-07-28\n\nVS Code/Copilot supports explicit workspace `.vscode/mcp.json` or user-profile MCP scope. Workspace credentials must not be hardcoded. Only valid non-symlink JSON with `mcpServers` can be changed.\n\n**Verification:** reread/schema-check the target, then use the MCP view/refresh flow and have the user confirm the server appears. Do not invoke a generated API tool.\n\n## gemini-cli\n\n**Official reference:** https://geminicli.com/docs/tools/mcp-server/\n**Retrieved:** 2026-07-28\n\nGemini CLI uses top-level `mcpServers` in explicit project or global `settings.json`. The plan records scope and no host/project secret values are read.\n\n**Verification:** reread/schema-check `settings.json`, restart Gemini CLI, and use its MCP inspection flow to confirm local discovery. Failed discovery rolls back this target only.\n\n## opencode\n\n**Official reference:** https://opencode.ai/docs/mcp-servers/\n**Retrieved:** 2026-07-28\n\nOpenCode supports local and remote MCP servers. `~/.config/opencode/opencode.json` is a **Linux/XDG example**, not a universal path. Native local servers are under `mcp.servers` with a command array. Prefer documented `opencode mcp add`; otherwise mutate only valid non-symlink JSON and fail closed if format differs.\n\n**Verification:** use OpenCode MCP server-management inspection after registration plus reread/schema-check of direct JSON writes. Confirm discovery without calling upstream tools.\n\n## Portable entry shape\n\n```json\n{\n  \"mcpServers\": {\n    \"example-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/generated-project/dist/index.js\"],\n      \"cwd\": \"/absolute/generated-project\"\n    }\n  }\n}\n```\n\nRequired environment variables are names only; users provide values outside generated artifacts and agent configuration.\n\nFile v0.2.4:references/type-mcp-runtime.md\n\n# TypeMCP Runtime Contract\n\nGenerated projects use the reviewed public npm package on the current 0.3.2 release line:\n\n```json\n\"@theorvane/type-mcp\": \"0.3.2\"\n```\n\n`@theorvane/type-mcp@0.3.2` is published with npm registry `gitHead` and GitHub Release `v0.3.2` both resolving to `e75bcf6a81ef4df57301b6154a0088845020886f`.\n\n## Allowed public API\n\nThe generator's default standard ESM path uses standard decorators from the public ESM/NodeNext entrypoint:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp\";\n```\n\nGenerated TypeScript uses only these public exports:\n\n- `@McpServer`\n- `@McpTool`\n- `createMcpServer`\n- `startStdioServer`\n- `zod`\n- an explicit `InstanceResolver`\n\n`createMcpServer` and `startStdioServer` are asynchronous and must be awaited. Standard decorators use TC39 semantics: generated `tsconfig.json` must not enable legacy `experimentalDecorators` or `emitDecoratorMetadata`.\n\n`@McpTool` requires an `input` Zod object. Generated code pins Zod v4 (`^4.4.3`) because that is the compatible public runtime contract for `@theorvane/type-mcp@0.3.2`.\n\n## Legacy decorator compatibility\n\nStandard and legacy decorators use distinct entrypoints and distinct decorator semantics. Legacy decorators are an opt-in public entrypoint for external CommonJS/Node16 projects that intentionally use TypeScript's legacy decorator mode; those projects must enable `experimentalDecorators` and import the decorators only from:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp/legacy\";\n```\n\nDo not mix this entrypoint with the standard ESM/NodeNext imports. The generator does not copy TypeMCP runtime source and must remain on its default standard ESM path; do not change its templates to legacy decorators or CommonJS.\n\n## Prohibited runtime boundaries\n\nNever generate or publish any of the following:\n\n- copied TypeMCP source code;\n- `file:`, `git:`, `link:`, or `portal:` dependencies;\n- imports from private, undocumented, or unavailable TypeMCP APIs;\n- local TypeMCP checkouts as a generated-project dependency.\n\nBefore generated lifecycle scripts run, contained verification inspects dependency metadata and the generated `package-lock.json`, then runs `npm ci --ignore-scripts` in a fresh isolated workspace with inherited npm proxy configuration disabled. It then typechecks, tests, builds, and executes a local stdio smoke test against a mock upstream. Use a host container/VM/sandbox when the dependency graph is untrusted.\n\nFile v0.2.4:skill-card.md\n\n## Description:\n\nUse when turning supplied API sources into a safe TypeMCP project.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[sjungwon03](https://clawhub.ai/user/sjungwon03)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineers use this skill to convert supplied local OpenAPI, Swagger, Swagger UI, Markdown, or HTML API references into a TypeMCP project with manifest review, generation approval, verification, and optional agent installation steps.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Optional agent installation can persistently register generated MCP servers in local agent configuration.\n\nMitigation: Prefer project-only generation or portable export unless the exact installation plan paths, command, args, cwd, environment variable names, and backups have been reviewed and separately approved.\n\nRisk: Generated-project verification can install and execute npm/node tooling for the generated dependency graph.\n\nMitigation: Run verification in a container, VM, or equivalent host sandbox when the generated project or dependency installation is untrusted.\n\nRisk: Security evidence reports a dependency-version documentation mismatch: docs claim @theorvane/type-mcp 0.3.2 while templates pin 0.2.0.\n\nMitigation: Verify the generated @theorvane/type-mcp dependency version and package-lock contents before relying on or publishing generated projects.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/sjungwon03/skills/api-to-typemcp)\n- [TypeMCP Runtime Contract](references/type-mcp-runtime.md)\n- [Agent MCP Installation Reference](references/agent-mcp-installation.md)\n- [Hermes MCP documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)\n- [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp)\n- [Codex CLI MCP reference](https://developers.openai.com/codex/cli/reference)\n- [Cursor MCP documentation](https://cursor.com/docs/mcp)\n- [VS Code MCP servers documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)\n- [Gemini CLI MCP server documentation](https://geminicli.com/docs/tools/mcp-server/)\n- [OpenCode MCP servers documentation](https://opencode.ai/docs/mcp-servers/)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, JSON, guidance]\n\n**Output Format:** [Markdown guidance, JSON manifests and plans, generated TypeScript project files, shell commands, and MCP server configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Project generation requires an explicitly supplied local API source, manifest review, digest-bound approval, an empty or explicitly replaced output directory, and separate confirmation for optional agent installation.]\n\n## Skill Version(s):\n\n0.2.4 (source: server release evidence and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.2.4:tests/fixtures/api-reference.md\n\n# Petstore API Reference\n\n## Authentication\n\nAll requests require an `api_key` header.\n\n## Endpoints\n\n### List Pets\n\n    GET /pets\n\nReturns all pets.\n\n### Get Pet by ID\n\n    GET /pets/{petId}\n\nReturns a single pet.\n\n### Create Pet\n\n    POST /pets\n\nCreates a new pet. Request body:\n\n```json\n{\"name\": \"Buddy\", \"status\": \"available\"}\n```\n\n### Delete Pet\n\n    DELETE /pets/{petId}\n\nDeletes a pet by ID.\n\n## Notes\n\nThe API rate limit is 100 requests per minute.\nContact support@example.com for access issues.\n\nFile v0.2.4:tests/fixtures/petstore.openapi.json\n\n{\n  \"openapi\": \"3.0.3\",\n  \"info\": {\"title\": \"Pet store\", \"version\": \"1.0.0\"},\n  \"servers\": [{\"url\": \"https://api.example.test/v1?api_key=fixture-secret-query\"}],\n  \"paths\": {\n    \"/pets/{petId}\": {\n      \"get\": {\n        \"operationId\": \"getPet\",\n        \"parameters\": [\n          {\"name\": \"petId\", \"in\": \"path\", \"required\": true, \"schema\": {\"type\": \"string\"}},\n          {\"name\": \"api_key\", \"in\": \"query\", \"schema\": {\"type\": \"string\", \"default\": \"fixture-secret-query\"}}\n        ],\n        \"responses\": {\"200\": {\"description\": \"A pet\"}}\n      }\n    },\n    \"/pets\": {\n      \"post\": {\n        \"operationId\": \"createPet\",\n        \"requestBody\": {\"required\": true, \"content\": {\"application/json\": {\"schema\": {\"type\": \"object\"}}}},\n        \"responses\": {\"201\": {\"description\": \"Created\"}}\n      }\n    }\n  }\n}\n\nFile v0.2.4:tests/fixtures/petstore.swagger.yaml\n\nswagger: \"2.0\"\ninfo:\n  title: Pet store\n  version: \"1.0.0\"\nhost: api.example.test\nbasePath: /v1\nschemes:\n  - https\npaths:\n  /pets/{petId}:\n    get:\n      operationId: getPet\n      parameters:\n        - name: petId\n          in: path\n          required: true\n          type: string\n      responses:\n        \"200\":\n          description: A pet\n  /pets:\n    post:\n      operationId: createPet\n      parameters:\n        - name: body\n          in: body\n          required: true\n          schema:\n            type: object\n      responses:\n        \"201\":\n          description: Created\n\nFile v0.2.4:requirements.txt\n\n# Required by `scripts/intake.py` for safe local YAML parsing.\nPyYAML==6.0.3\n\nArchive v0.2.3: 52 files, 108594 bytes\n\nFiles: references/agent-mcp-installation.md (5525b), references/type-mcp-runtime.md (2463b), requirements.txt (77b), scripts/agent_clients.py (4854b), scripts/api_to_typemcp.py (15284b), scripts/approval.py (6293b), scripts/config_codecs.py (1631b), scripts/documents.py (3785b), scripts/install_mcp.py (15565b), scripts/install_plan.py (7585b), scripts/intake.py (7300b), scripts/manifest.py (762b), scripts/policy.py (1543b), scripts/render.py (16514b), scripts/structured_specs.py (16750b), scripts/swagger_ui.py (2075b), scripts/verify_generated.py (11452b), skill-card.md (2674b), SKILL.md (10011b), templates/typescript-stdio/package-lock.json.tmpl (87670b), templates/typescript-stdio/package.json.tmpl (463b), templates/typescript-stdio/README.md.tmpl (962b), templates/typescript-stdio/src/api-client.ts.tmpl (1751b), templates/typescript-stdio/src/index.ts.tmpl (255b), templates/typescript-stdio/src/policy.ts.tmpl (1665b), templates/typescript-stdio/tsconfig.json.tmpl (278b), tests/fixtures/api-reference.html (632b), tests/fixtures/api-reference.md (504b), tests/fixtures/mock_upstream.py (3915b), tests/fixtures/petstore.openapi.json (804b), tests/fixtures/petstore.swagger.yaml (579b), tests/fixtures/swagger-ui.html (434b), tests/test_agent_clients.py (3804b), tests/test_agent_installation_docs.py (1522b), tests/test_approval.py (6165b), tests/test_cli_agent_adapters.py (8177b), tests/test_config_codecs.py (1672b), tests/test_document_intake.py (4595b), tests/test_documents.py (6012b), tests/test_engine_cli.py (9325b), tests/test_generated_project_e2e.py (9879b), tests/test_generated_project_static.py (7946b), tests/test_install_mcp.py (6505b), tests/test_install_plan.py (6737b), tests/test_manifest.py (14717b), tests/test_output_safety.py (9128b), tests/test_policy.py (1512b), tests/test_render.py (10488b), tests/test_runtime_documentation.py (2455b), tests/test_swagger_ui.py (3218b), tests/test_verify_generated_security.py (2102b), _meta.json (133b)\n\nFile v0.2.3:SKILL.md\n\n---\nname: api-to-typemcp\ndescription: Use when turning supplied API sources into a safe TypeMCP project.\nversion: 0.2.3\ncategory: integration\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [mcp, api, openapi, swagger, code-generation, type-mcp]\n    related_skills: []\n  openclaw:\n    requires:\n      bins: [python3, node, npm]\n    envVars:\n      - name: TYPE_MCP_APPROVAL_STATE_DIR\n        required: false\n        description: Isolated directory for single-use generation approvals.\n      - name: TYPE_MCP_BASE_URL\n        required: false\n        description: Local test upstream used only by contained verification.\n---\n\n# API to TypeMCP\n\n## Overview\n\nThis released skill is a complete, bundled generator delivery unit. Its **bundled skill engine** is in `scripts/`, its controlled TypeScript output templates are in `templates/`, and its public TypeMCP runtime constraints are in [references/type-mcp-runtime.md](references/type-mcp-runtime.md).\n\nGenerated projects use the current published `@theorvane/type-mcp@0.3.2` release line and only its public package exports; they never copy TypeMCP source or use local, `file:`, `git:`, `link:`, or private runtime APIs. The npm registry `gitHead` and GitHub Release `v0.3.2` both resolve to `e75bcf6a81ef4df57301b6154a0088845020886f`.\n\n## When to use\n\nUse this skill with a **supplied local** OpenAPI 3.x / Swagger 2.0 JSON/YAML file, supplied Swagger UI HTML, or supplied Markdown/HTML API reference. Do not use it to crawl a bare origin, infer undocumented operations, make mutating calls by default, or publish without explicit final confirmation.\n\n## Execution permissions and containment boundary\n\nThe engine reads only the user-supplied source and files bundled with this skill. It writes only the caller-created output directory and the optional `TYPE_MCP_APPROVAL_STATE_DIR`; it never modifies an upstream API or publishes a repository without the separate explicit gates below.\n\nThe engine invokes `python3`. Optional generated-project verification additionally invokes `npm` and `node`, uses a fresh temporary workspace, passes a credential-scrubbed environment, disables inherited npm proxy settings and lifecycle scripts, and installs exactly the generated `package-lock.json` graph with `npm ci`. That install requires outbound access to the npm registry; the generator itself performs no network fetch or crawling, and the smoke test targets only a caller-provided local test upstream.\n\nThis verifier is **process containment**, not a claim of kernel or network isolation. Run it in a container, VM, or an equivalent host sandbox when the generated project or its dependency installation is untrusted.\n\n## Bundled engine workflow\n\nRun the engine through its installed skill-relative path. Set `SKILL_DIR` to the directory containing this `SKILL.md`; create a **controlled temporary output directory** yourself and keep it empty.\n\n```bash\nSKILL_DIR=\"/absolute/path/to/api-to-typemcp\"\nSOURCE=\"/absolute/path/to/supplied-openapi.json\"\nOUTPUT=\"$(mktemp -d -t api-to-typemcp-output.XXXXXX)\"\nSTATE=\"$(mktemp -d -t api-to-typemcp-state.XXXXXX)\"\nexport TYPE_MCP_APPROVAL_STATE_DIR=\"$STATE\"\n\n# 1. Inspect and build the exact secret-free manifest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" inspect --file \"$SOURCE\" --json\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest --file \"$SOURCE\" --json > manifest.json\nDIGEST=\"$(python3 -c 'import json; print(json.load(open(\"manifest.json\"))[\"digest\"])')\"\n\n# 2. Review the manifest, then explicitly approve precisely that digest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" approve \\\n  --file \"$SOURCE\" --manifest-digest \"$DIGEST\"\n\n# 3. Render only after approval, with an exact digest confirmation.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" generate \\\n  --file \"$SOURCE\" --output \"$OUTPUT\" \\\n  --confirm-manifest-digest \"$DIGEST\"\n```\n\nFor supplied Markdown or HTML, add an explicit origin; no page is fetched or crawled:\n\n```bash\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest \\\n  --file \"/absolute/path/to/reference.md\" \\\n  --base-url \"https://api.example.test\" --json\n```\n\nSwagger UI discovery is performed by `inspect` in-memory and returns only an explicit configured spec reference. The user must separately supply that structured spec; do not fetch it automatically.\n\n## Mandatory safety gates\n\n1. **Manifest first.** Treat every source as untrusted. Review canonical secret-free manifest data before generation.\n2. **Receipt gate.** `approve` issues a HMAC-protected, digest-bound, single-use receipt. A changed, expired, tampered, or already-consumed receipt stops `generate`.\n3. **Output gate.** The output directory must already exist and be empty unless `--replace` is explicitly supplied. Symlinks and `..` traversal are rejected.\n4. **Runtime policy.** `GET`/`HEAD`/`OPTIONS` are read operations. `POST`/`PUT`/`PATCH`/`DELETE` are protected writes and require exact known IDs in `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS` **before URL, query, headers, body, authentication, or dispatch**. Unknown methods deny.\n5. **Containment.** Verify generated projects in a scrubbed temporary workspace, after package inspection and with a generated lockfile. Use `npm ci --ignore-scripts` with inherited proxy settings disabled, then typecheck, test, build, and run a local MCP stdio smoke test. Use a container, VM, or equivalent host sandbox when the project or dependency graph is untrusted.\n6. **Agent installation (optional).** After a verified project is generated, ask whether the user wants **project only** or **project + agent installation**. Project-only is the default. For installation, detect clients read-only, present the detected targets and exact config paths/command/args/cwd/env *names* plus backup paths, and require a separate final confirmation bound to the reviewed installation plan. Never read `.env`, copy secret values, silently replace a server name, or mutate an undetected/unsupported client; provide a portable `mcpServers.json` export instead.\n7. **Publication.** **Immediately before GitHub publication**, record owner/org, repository name, visibility, and source branch. Resolve the actual checked-out/ref-to-publish branch and stop unless it exactly equals the recorded source branch. Ask for explicit user confirmation before the publication action.\n\n## Optional agent installation workflow\n\nOnly use this after generated-project verification succeeds. Read-only discovery covers Hermes, Claude Code, Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode. This release has verified native config adapters for **Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode**, plus official CLI adapters for **Hermes** (`hermes mcp add` then `hermes mcp test`) and **Claude Code** (`claude mcp add --transport stdio` then `claude mcp list`). Hermes and Claude Code configuration files are never guessed or edited directly. If either CLI is missing or its add/verification action fails, the adapter removes a just-added server when possible and reports the target as failed; use portable export instead.\n\n```bash\n# 1. The assistant asks: \"프로젝트만 생성할까요, 아니면 생성 후 에이전트에 탑재할까요?\"\n# 2. For install, inspect and show a secret-free plan before any config write.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-plan \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\"\n\n# 3. Review the preview, then explicitly issue the plan-bound one-time confirmation.\nPLAN_DIGEST=\"...shown by install-plan...\"\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-approve --plan-digest \"$PLAN_DIGEST\"\n\n# 4. Apply only the unchanged approved plan. Native registration is fail-closed\n#    unless the selected client already has a detected regular config file. Each\n#    target gets a 0600 backup; a later target failure restores earlier targets,\n#    and every write is reread/parsed before success is reported.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-apply \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\" --confirm-plan-digest \"$PLAN_DIGEST\"\n```\n\nFor no-write portability, use `install-export --project \"$OUTPUT\"`; it writes only\n`$OUTPUT/agent-install/mcpServers.json`, never an agent configuration. Preview and\nreceipts expose `env_names` only—never `.env` content or credential values.\n\n## Runtime compatibility\n\nRead [references/type-mcp-runtime.md](references/type-mcp-runtime.md) before modifying generated TypeScript. The default generated standard ESM path uses the public ESM/NodeNext decorator import:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp\";\n```\n\nUse only `McpServer`, `McpTool`, `createMcpServer`, `startStdioServer`, `zod`, and an explicit `InstanceResolver` from the public contract. Legacy decorators are a separate, opt-in compatibility surface for CommonJS/Node16 projects that enable `experimentalDecorators`:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp/legacy\";\n```\n\nThese are distinct entrypoints with distinct decorator semantics. Do not change the generator templates to the legacy/CommonJS path; generated projects remain standard ESM consumers and never copy runtime source.\n\n## Verification checklist\n\n- [ ] Source is supplied explicitly; no origin crawling occurred.\n- [ ] Manifest is secret-free, evidence-backed, and canonically digested.\n- [ ] Digest approval and a valid single-use receipt precede generation.\n- [ ] Output target passed the empty/replace and traversal/symlink safety gates.\n- [ ] Protected writes are authorized before request construction.\n- [ ] Generated project uses the published `@theorvane/type-mcp@0.3.2` release line only and includes a reviewed `package-lock.json`; confirm registry provenance before changing this version.\n- [ ] Contained `npm ci --ignore-scripts`/typecheck/test/build/MCP smoke passes; external sandboxing is used for untrusted dependency installation.\n- [ ] Immediately before GitHub publication, user confirms owner/name/visibility/source branch and the resolved branch matches.\n\nFile v0.2.3:_meta.json\n\n{\n  \"ownerId\": \"kn701ftcm7pjm5537hh2jnv7y18b5q10\",\n  \"slug\": \"api-to-typemcp\",\n  \"version\": \"0.2.3\",\n  \"publishedAt\": 1786578699449\n}\n\nFile v0.2.3:references/agent-mcp-installation.md\n\n# Agent MCP Installation Reference\n\n**Status:** implementation contract\n**Retrieved:** 2026-07-28\n\n`api-to-typemcp` produces local stdio MCP projects. Project-only generation is the default. Only after contained generated-project verification may the skill offer agent installation. Detection is read-only; installation requires selected targets, a displayed secret-free plan, and a separate final confirmation.\n\n## Global safety contract\n\n- The installer never reads `.env`, resolves credentials, or writes secret values into an agent config, plan, log, backup, or portable export. It displays environment-variable names only.\n- `generate` never scans or edits agent configuration.\n- Unknown, malformed, symlinked, fingerprint-changed, or unsupported targets fail closed.\n- Portable export does not modify an agent configuration. It writes a secret-free standard `mcpServers` snippet under generated-project `agent-install/`.\n- Per-target failure never implies another target is installed; a changed target has a same-directory backup and target-local rollback.\n- Protected writes remain fail-closed under `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS`.\n\n## hermes\n\n**Official reference:** https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses only the documented `hermes mcp add <name> --command node --args <absolute-entry>` CLI path. The reviewed plan records the CLI-managed candidate path for operator visibility but the installer never reads or edits it directly. After registration, it runs `hermes mcp test <name>`; any non-zero result triggers `hermes mcp remove <name>` as compensating rollback. Hermes CLI currently exposes no cwd flag, so the generated absolute `dist/index.js` entrypoint is used and the plan reports the canonical project cwd for review. Environment variable values are never read or passed; users provide required values through their Hermes execution environment.\n\n## claude-code\n\n**Official reference:** https://docs.anthropic.com/en/docs/claude-code/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses the documented stdio form `claude mcp add --transport stdio <name> -- node <absolute-entry>`, where `--` separates Claude Code options from the server command. The installer never reads or edits Claude settings directly. It verifies registration using `claude mcp list` and requires the named server in successful output; a failed or absent discovery triggers `claude mcp remove <name>` as compensating rollback. Claude Code’s documented add form has no cwd argument, so the generated absolute entrypoint is used and the canonical project cwd remains plan-visible only. Environment variable values are never read or passed; users provide required values through their Claude Code execution environment.\n\n## codex\n\n**Official reference:** https://developers.openai.com/codex/cli/reference\n**Retrieved:** 2026-07-28\n\nPreferred path: `codex mcp add`, `codex mcp get`, and `codex mcp list`. Native entries use TOML `mcp_servers`. Without a safe CLI path, append only a missing validated table; reject existing target tables or syntax that cannot be preserved.\n\n## cursor\n\n**Official reference:** https://cursor.com/docs/mcp\n**Retrieved:** 2026-07-28\n\nCursor uses a selected user/workspace JSON `mcpServers` object in `mcp.json`. Direct mutation is only for valid non-symlink JSON with preservation guarantees; otherwise return portable export.\n\n**Verification:** reread/schema-check the exact target, then reload Cursor MCP configuration or restart and have the user confirm the named server appears. Do not call an upstream API tool.\n\n## vscode-copilot\n\n**Official reference:** https://code.visualstudio.com/docs/agent-customization/mcp-servers\n**Retrieved:** 2026-07-28\n\nVS Code/Copilot supports explicit workspace `.vscode/mcp.json` or user-profile MCP scope. Workspace credentials must not be hardcoded. Only valid non-symlink JSON with `mcpServers` can be changed.\n\n**Verification:** reread/schema-check the target, then use the MCP view/refresh flow and have the user confirm the server appears. Do not invoke a generated API tool.\n\n## gemini-cli\n\n**Official reference:** https://geminicli.com/docs/tools/mcp-server/\n**Retrieved:** 2026-07-28\n\nGemini CLI uses top-level `mcpServers` in explicit project or global `settings.json`. The plan records scope and no host/project secret values are read.\n\n**Verification:** reread/schema-check `settings.json`, restart Gemini CLI, and use its MCP inspection flow to confirm local discovery. Failed discovery rolls back this target only.\n\n## opencode\n\n**Official reference:** https://opencode.ai/docs/mcp-servers/\n**Retrieved:** 2026-07-28\n\nOpenCode supports local and remote MCP servers. `~/.config/opencode/opencode.json` is a **Linux/XDG example**, not a universal path. Native local servers are under `mcp.servers` with a command array. Prefer documented `opencode mcp add`; otherwise mutate only valid non-symlink JSON and fail closed if format differs.\n\n**Verification:** use OpenCode MCP server-management inspection after registration plus reread/schema-check of direct JSON writes. Confirm discovery without calling upstream tools.\n\n## Portable entry shape\n\n```json\n{\n  \"mcpServers\": {\n    \"example-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/generated-project/dist/index.js\"],\n      \"cwd\": \"/absolute/generated-project\"\n    }\n  }\n}\n```\n\nRequired environment variables are names only; users provide values outside generated artifacts and agent configuration.\n\nFile v0.2.3:references/type-mcp-runtime.md\n\n# TypeMCP Runtime Contract\n\nGenerated projects use the reviewed public npm package on the current 0.3.2 release line:\n\n```json\n\"@theorvane/type-mcp\": \"0.3.2\"\n```\n\n`@theorvane/type-mcp@0.3.2` is published with npm registry `gitHead` and GitHub Release `v0.3.2` both resolving to `e75bcf6a81ef4df57301b6154a0088845020886f`.\n\n## Allowed public API\n\nThe generator's default standard ESM path uses standard decorators from the public ESM/NodeNext entrypoint:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp\";\n```\n\nGenerated TypeScript uses only these public exports:\n\n- `@McpServer`\n- `@McpTool`\n- `createMcpServer`\n- `startStdioServer`\n- `zod`\n- an explicit `InstanceResolver`\n\n`createMcpServer` and `startStdioServer` are asynchronous and must be awaited. Standard decorators use TC39 semantics: generated `tsconfig.json` must not enable legacy `experimentalDecorators` or `emitDecoratorMetadata`.\n\n`@McpTool` requires an `input` Zod object. Generated code pins Zod v4 (`^4.4.3`) because that is the compatible public runtime contract for `@theorvane/type-mcp@0.3.2`.\n\n## Legacy decorator compatibility\n\nStandard and legacy decorators use distinct entrypoints and distinct decorator semantics. Legacy decorators are an opt-in public entrypoint for external CommonJS/Node16 projects that intentionally use TypeScript's legacy decorator mode; those projects must enable `experimentalDecorators` and import the decorators only from:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp/legacy\";\n```\n\nDo not mix this entrypoint with the standard ESM/NodeNext imports. The generator does not copy TypeMCP runtime source and must remain on its default standard ESM path; do not change its templates to legacy decorators or CommonJS.\n\n## Prohibited runtime boundaries\n\nNever generate or publish any of the following:\n\n- copied TypeMCP source code;\n- `file:`, `git:`, `link:`, or `portal:` dependencies;\n- imports from private, undocumented, or unavailable TypeMCP APIs;\n- local TypeMCP checkouts as a generated-project dependency.\n\nBefore generated lifecycle scripts run, contained verification inspects dependency metadata and the generated `package-lock.json`, then runs `npm ci --ignore-scripts` in a fresh isolated workspace with inherited npm proxy configuration disabled. It then typechecks, tests, builds, and executes a local stdio smoke test against a mock upstream. Use a host container/VM/sandbox when the dependency graph is untrusted.\n\nFile v0.2.3:skill-card.md\n\n## Description:\n\nUse when turning supplied API sources into a safe TypeMCP project.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[sjungwon03](https://clawhub.ai/user/sjungwon03)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineers use this skill to convert supplied local OpenAPI, Swagger, Swagger UI, Markdown, or HTML API references into local TypeMCP stdio projects with manifest review, digest-bound approval, and generated-project verification gates.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Optional agent installation can persistently modify local MCP configuration.\n\nMitigation: Use project-only mode by default; install only after reviewing the exact plan paths, command, arguments, working directory, environment variable names, and backup paths.\n\nRisk: Runtime-version evidence conflicts: documentation says generated projects use @theorvane/type-mcp 0.3.2, while the bundled package template pins 0.2.0.\n\nMitigation: Verify the generated package dependency version and lockfile before using, verifying, or publishing a generated project.\n\nRisk: Generated-project verification may install dependencies from the npm registry.\n\nMitigation: Run verification in a container, VM, or equivalent host sandbox when the generated project or dependency graph is untrusted.\n\n## Reference(s):\n\n- [TypeMCP Runtime Contract](references/type-mcp-runtime.md)\n- [Agent MCP Installation Reference](references/agent-mcp-installation.md)\n- [Hermes MCP documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)\n- [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp)\n- [Codex CLI MCP reference](https://developers.openai.com/codex/cli/reference)\n- [Cursor MCP documentation](https://cursor.com/docs/mcp)\n- [VS Code MCP servers documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell commands and generated project files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces a local TypeScript stdio MCP project, optional agent installation plans or exports, and verification guidance.]\n\n## Skill Version(s):\n\n0.2.3 (source: frontmatter and server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.2.3:tests/fixtures/api-reference.md\n\n# Petstore API Reference\n\n## Authentication\n\nAll requests require an `api_key` header.\n\n## Endpoints\n\n### List Pets\n\n    GET /pets\n\nReturns all pets.\n\n### Get Pet by ID\n\n    GET /pets/{petId}\n\nReturns a single pet.\n\n### Create Pet\n\n    POST /pets\n\nCreates a new pet. Request body:\n\n```json\n{\"name\": \"Buddy\", \"status\": \"available\"}\n```\n\n### Delete Pet\n\n    DELETE /pets/{petId}\n\nDeletes a pet by ID.\n\n## Notes\n\nThe API rate limit is 100 requests per minute.\nContact support@example.com for access issues.\n\nFile v0.2.3:tests/fixtures/petstore.openapi.json\n\n{\n  \"openapi\": \"3.0.3\",\n  \"info\": {\"title\": \"Pet store\", \"version\": \"1.0.0\"},\n  \"servers\": [{\"url\": \"https://api.example.test/v1?api_key=fixture-secret-query\"}],\n  \"paths\": {\n    \"/pets/{petId}\": {\n      \"get\": {\n        \"operationId\": \"getPet\",\n        \"parameters\": [\n          {\"name\": \"petId\", \"in\": \"path\", \"required\": true, \"schema\": {\"type\": \"string\"}},\n          {\"name\": \"api_key\", \"in\": \"query\", \"schema\": {\"type\": \"string\", \"default\": \"fixture-secret-query\"}}\n        ],\n        \"responses\": {\"200\": {\"description\": \"A pet\"}}\n      }\n    },\n    \"/pets\": {\n      \"post\": {\n        \"operationId\": \"createPet\",\n        \"requestBody\": {\"required\": true, \"content\": {\"application/json\": {\"schema\": {\"type\": \"object\"}}}},\n        \"responses\": {\"201\": {\"description\": \"Created\"}}\n      }\n    }\n  }\n}\n\nFile v0.2.3:tests/fixtures/petstore.swagger.yaml\n\nswagger: \"2.0\"\ninfo:\n  title: Pet store\n  version: \"1.0.0\"\nhost: api.example.test\nbasePath: /v1\nschemes:\n  - https\npaths:\n  /pets/{petId}:\n    get:\n      operationId: getPet\n      parameters:\n        - name: petId\n          in: path\n          required: true\n          type: string\n      responses:\n        \"200\":\n          description: A pet\n  /pets:\n    post:\n      operationId: createPet\n      parameters:\n        - name: body\n          in: body\n          required: true\n          schema:\n            type: object\n      responses:\n        \"201\":\n          description: Created\n\nFile v0.2.3:requirements.txt\n\n# Required by `scripts/intake.py` for safe local YAML parsing.\nPyYAML==6.0.3\n\nArchive v0.2.2: 51 files, 106822 bytes\n\nFiles: references/agent-mcp-installation.md (5525b), references/type-mcp-runtime.md (1425b), requirements.txt (77b), scripts/agent_clients.py (4854b), scripts/api_to_typemcp.py (15284b), scripts/approval.py (6293b), scripts/config_codecs.py (1631b), scripts/documents.py (3785b), scripts/install_mcp.py (15565b), scripts/install_plan.py (7585b), scripts/intake.py (7300b), scripts/manifest.py (762b), scripts/policy.py (1543b), scripts/render.py (16514b), scripts/structured_specs.py (16750b), scripts/swagger_ui.py (2075b), scripts/verify_generated.py (11452b), skill-card.md (2997b), SKILL.md (9194b), templates/typescript-stdio/package-lock.json.tmpl (87670b), templates/typescript-stdio/package.json.tmpl (463b), templates/typescript-stdio/README.md.tmpl (962b), templates/typescript-stdio/src/api-client.ts.tmpl (1751b), templates/typescript-stdio/src/index.ts.tmpl (255b), templates/typescript-stdio/src/policy.ts.tmpl (1665b), templates/typescript-stdio/tsconfig.json.tmpl (278b), tests/fixtures/api-reference.html (632b), tests/fixtures/api-reference.md (504b), tests/fixtures/mock_upstream.py (3915b), tests/fixtures/petstore.openapi.json (804b), tests/fixtures/petstore.swagger.yaml (579b), tests/fixtures/swagger-ui.html (434b), tests/test_agent_clients.py (3804b), tests/test_agent_installation_docs.py (1522b), tests/test_approval.py (6165b), tests/test_cli_agent_adapters.py (8177b), tests/test_config_codecs.py (1672b), tests/test_document_intake.py (4595b), tests/test_documents.py (6012b), tests/test_engine_cli.py (9325b), tests/test_generated_project_e2e.py (9879b), tests/test_generated_project_static.py (7946b), tests/test_install_mcp.py (6505b), tests/test_install_plan.py (6737b), tests/test_manifest.py (14717b), tests/test_output_safety.py (9128b), tests/test_policy.py (1512b), tests/test_render.py (10488b), tests/test_swagger_ui.py (3218b), tests/test_verify_generated_security.py (2102b), _meta.json (133b)\n\nFile v0.2.2:SKILL.md\n\n---\nname: api-to-typemcp\ndescription: Use when turning supplied API sources into a safe TypeMCP project.\nversion: 0.2.2\ncategory: integration\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [mcp, api, openapi, swagger, code-generation, type-mcp]\n    related_skills: []\n  openclaw:\n    requires:\n      bins: [python3, node, npm]\n    envVars:\n      - name: TYPE_MCP_APPROVAL_STATE_DIR\n        required: false\n        description: Isolated directory for single-use generation approvals.\n      - name: TYPE_MCP_BASE_URL\n        required: false\n        description: Local test upstream used only by contained verification.\n---\n\n# API to TypeMCP\n\n## Overview\n\nThis released skill is a complete, bundled generator delivery unit. Its **bundled skill engine** is in `scripts/`, its controlled TypeScript output templates are in `templates/`, and its public TypeMCP runtime constraints are in [references/type-mcp-runtime.md](references/type-mcp-runtime.md).\n\nGenerated projects depend only on published `@theorvane/type-mcp@0.2.0`; they never copy TypeMCP source or use local, `file:`, `git:`, `link:`, or private runtime APIs.\n\n## When to use\n\nUse this skill with a **supplied local** OpenAPI 3.x / Swagger 2.0 JSON/YAML file, supplied Swagger UI HTML, or supplied Markdown/HTML API reference. Do not use it to crawl a bare origin, infer undocumented operations, make mutating calls by default, or publish without explicit final confirmation.\n\n## Execution permissions and containment boundary\n\nThe engine reads only the user-supplied source and files bundled with this skill. It writes only the caller-created output directory and the optional `TYPE_MCP_APPROVAL_STATE_DIR`; it never modifies an upstream API or publishes a repository without the separate explicit gates below.\n\nThe engine invokes `python3`. Optional generated-project verification additionally invokes `npm` and `node`, uses a fresh temporary workspace, passes a credential-scrubbed environment, disables inherited npm proxy settings and lifecycle scripts, and installs exactly the generated `package-lock.json` graph with `npm ci`. That install requires outbound access to the npm registry; the generator itself performs no network fetch or crawling, and the smoke test targets only a caller-provided local test upstream.\n\nThis verifier is **process containment**, not a claim of kernel or network isolation. Run it in a container, VM, or an equivalent host sandbox when the generated project or its dependency installation is untrusted.\n\n## Bundled engine workflow\n\nRun the engine through its installed skill-relative path. Set `SKILL_DIR` to the directory containing this `SKILL.md`; create a **controlled temporary output directory** yourself and keep it empty.\n\n```bash\nSKILL_DIR=\"/absolute/path/to/api-to-typemcp\"\nSOURCE=\"/absolute/path/to/supplied-openapi.json\"\nOUTPUT=\"$(mktemp -d -t api-to-typemcp-output.XXXXXX)\"\nSTATE=\"$(mktemp -d -t api-to-typemcp-state.XXXXXX)\"\nexport TYPE_MCP_APPROVAL_STATE_DIR=\"$STATE\"\n\n# 1. Inspect and build the exact secret-free manifest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" inspect --file \"$SOURCE\" --json\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest --file \"$SOURCE\" --json > manifest.json\nDIGEST=\"$(python3 -c 'import json; print(json.load(open(\"manifest.json\"))[\"digest\"])')\"\n\n# 2. Review the manifest, then explicitly approve precisely that digest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" approve \\\n  --file \"$SOURCE\" --manifest-digest \"$DIGEST\"\n\n# 3. Render only after approval, with an exact digest confirmation.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" generate \\\n  --file \"$SOURCE\" --output \"$OUTPUT\" \\\n  --confirm-manifest-digest \"$DIGEST\"\n```\n\nFor supplied Markdown or HTML, add an explicit origin; no page is fetched or crawled:\n\n```bash\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest \\\n  --file \"/absolute/path/to/reference.md\" \\\n  --base-url \"https://api.example.test\" --json\n```\n\nSwagger UI discovery is performed by `inspect` in-memory and returns only an explicit configured spec reference. The user must separately supply that structured spec; do not fetch it automatically.\n\n## Mandatory safety gates\n\n1. **Manifest first.** Treat every source as untrusted. Review canonical secret-free manifest data before generation.\n2. **Receipt gate.** `approve` issues a HMAC-protected, digest-bound, single-use receipt. A changed, expired, tampered, or already-consumed receipt stops `generate`.\n3. **Output gate.** The output directory must already exist and be empty unless `--replace` is explicitly supplied. Symlinks and `..` traversal are rejected.\n4. **Runtime policy.** `GET`/`HEAD`/`OPTIONS` are read operations. `POST`/`PUT`/`PATCH`/`DELETE` are protected writes and require exact known IDs in `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS` **before URL, query, headers, body, authentication, or dispatch**. Unknown methods deny.\n5. **Containment.** Verify generated projects in a scrubbed temporary workspace, after package inspection and with a generated lockfile. Use `npm ci --ignore-scripts` with inherited proxy settings disabled, then typecheck, test, build, and run a local MCP stdio smoke test. Use a container, VM, or equivalent host sandbox when the project or dependency graph is untrusted.\n6. **Agent installation (optional).** After a verified project is generated, ask whether the user wants **project only** or **project + agent installation**. Project-only is the default. For installation, detect clients read-only, present the detected targets and exact config paths/command/args/cwd/env *names* plus backup paths, and require a separate final confirmation bound to the reviewed installation plan. Never read `.env`, copy secret values, silently replace a server name, or mutate an undetected/unsupported client; provide a portable `mcpServers.json` export instead.\n7. **Publication.** **Immediately before GitHub publication**, record owner/org, repository name, visibility, and source branch. Resolve the actual checked-out/ref-to-publish branch and stop unless it exactly equals the recorded source branch. Ask for explicit user confirmation before the publication action.\n\n## Optional agent installation workflow\n\nOnly use this after generated-project verification succeeds. Read-only discovery covers Hermes, Claude Code, Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode. This release has verified native config adapters for **Codex, Cursor, VS Code/Copilot, Gemini CLI, and OpenCode**, plus official CLI adapters for **Hermes** (`hermes mcp add` then `hermes mcp test`) and **Claude Code** (`claude mcp add --transport stdio` then `claude mcp list`). Hermes and Claude Code configuration files are never guessed or edited directly. If either CLI is missing or its add/verification action fails, the adapter removes a just-added server when possible and reports the target as failed; use portable export instead.\n\n```bash\n# 1. The assistant asks: \"프로젝트만 생성할까요, 아니면 생성 후 에이전트에 탑재할까요?\"\n# 2. For install, inspect and show a secret-free plan before any config write.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-plan \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\"\n\n# 3. Review the preview, then explicitly issue the plan-bound one-time confirmation.\nPLAN_DIGEST=\"...shown by install-plan...\"\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-approve --plan-digest \"$PLAN_DIGEST\"\n\n# 4. Apply only the unchanged approved plan. Native registration is fail-closed\n#    unless the selected client already has a detected regular config file. Each\n#    target gets a 0600 backup; a later target failure restores earlier targets,\n#    and every write is reread/parsed before success is reported.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-apply \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\" --confirm-plan-digest \"$PLAN_DIGEST\"\n```\n\nFor no-write portability, use `install-export --project \"$OUTPUT\"`; it writes only\n`$OUTPUT/agent-install/mcpServers.json`, never an agent configuration. Preview and\nreceipts expose `env_names` only—never `.env` content or credential values.\n\n## Runtime compatibility\n\nRead [references/type-mcp-runtime.md](references/type-mcp-runtime.md) before modifying generated TypeScript. Use only `McpServer`, `McpTool`, `createMcpServer`, `startStdioServer`, `zod`, and an explicit `InstanceResolver` from the public contract.\n\n## Verification checklist\n\n- [ ] Source is supplied explicitly; no origin crawling occurred.\n- [ ] Manifest is secret-free, evidence-backed, and canonically digested.\n- [ ] Digest approval and a valid single-use receipt precede generation.\n- [ ] Output target passed the empty/replace and traversal/symlink safety gates.\n- [ ] Protected writes are authorized before request construction.\n- [ ] Generated project uses published `@theorvane/type-mcp@0.2.0` only and includes a reviewed `package-lock.json`.\n- [ ] Contained `npm ci --ignore-scripts`/typecheck/test/build/MCP smoke passes; external sandboxing is used for untrusted dependency installation.\n- [ ] Immediately before GitHub publication, user confirms owner/name/visibility/source branch and the resolved branch matches.\n\nFile v0.2.2:_meta.json\n\n{\n  \"ownerId\": \"kn701ftcm7pjm5537hh2jnv7y18b5q10\",\n  \"slug\": \"api-to-typemcp\",\n  \"version\": \"0.2.2\",\n  \"publishedAt\": 1785303011325\n}\n\nFile v0.2.2:references/agent-mcp-installation.md\n\n# Agent MCP Installation Reference\n\n**Status:** implementation contract\n**Retrieved:** 2026-07-28\n\n`api-to-typemcp` produces local stdio MCP projects. Project-only generation is the default. Only after contained generated-project verification may the skill offer agent installation. Detection is read-only; installation requires selected targets, a displayed secret-free plan, and a separate final confirmation.\n\n## Global safety contract\n\n- The installer never reads `.env`, resolves credentials, or writes secret values into an agent config, plan, log, backup, or portable export. It displays environment-variable names only.\n- `generate` never scans or edits agent configuration.\n- Unknown, malformed, symlinked, fingerprint-changed, or unsupported targets fail closed.\n- Portable export does not modify an agent configuration. It writes a secret-free standard `mcpServers` snippet under generated-project `agent-install/`.\n- Per-target failure never implies another target is installed; a changed target has a same-directory backup and target-local rollback.\n- Protected writes remain fail-closed under `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS`.\n\n## hermes\n\n**Official reference:** https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses only the documented `hermes mcp add <name> --command node --args <absolute-entry>` CLI path. The reviewed plan records the CLI-managed candidate path for operator visibility but the installer never reads or edits it directly. After registration, it runs `hermes mcp test <name>`; any non-zero result triggers `hermes mcp remove <name>` as compensating rollback. Hermes CLI currently exposes no cwd flag, so the generated absolute `dist/index.js` entrypoint is used and the plan reports the canonical project cwd for review. Environment variable values are never read or passed; users provide required values through their Hermes execution environment.\n\n## claude-code\n\n**Official reference:** https://docs.anthropic.com/en/docs/claude-code/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses the documented stdio form `claude mcp add --transport stdio <name> -- node <absolute-entry>`, where `--` separates Claude Code options from the server command. The installer never reads or edits Claude settings directly. It verifies registration using `claude mcp list` and requires the named server in successful output; a failed or absent discovery triggers `claude mcp remove <name>` as compensating rollback. Claude Code’s documented add form has no cwd argument, so the generated absolute entrypoint is used and the canonical project cwd remains plan-visible only. Environment variable values are never read or passed; users provide required values through their Claude Code execution environment.\n\n## codex\n\n**Official reference:** https://developers.openai.com/codex/cli/reference\n**Retrieved:** 2026-07-28\n\nPreferred path: `codex mcp add`, `codex mcp get`, and `codex mcp list`. Native entries use TOML `mcp_servers`. Without a safe CLI path, append only a missing validated table; reject existing target tables or syntax that cannot be preserved.\n\n## cursor\n\n**Official reference:** https://cursor.com/docs/mcp\n**Retrieved:** 2026-07-28\n\nCursor uses a selected user/workspace JSON `mcpServers` object in `mcp.json`. Direct mutation is only for valid non-symlink JSON with preservation guarantees; otherwise return portable export.\n\n**Verification:** reread/schema-check the exact target, then reload Cursor MCP configuration or restart and have the user confirm the named server appears. Do not call an upstream API tool.\n\n## vscode-copilot\n\n**Official reference:** https://code.visualstudio.com/docs/agent-customization/mcp-servers\n**Retrieved:** 2026-07-28\n\nVS Code/Copilot supports explicit workspace `.vscode/mcp.json` or user-profile MCP scope. Workspace credentials must not be hardcoded. Only valid non-symlink JSON with `mcpServers` can be changed.\n\n**Verification:** reread/schema-check the target, then use the MCP view/refresh flow and have the user confirm the server appears. Do not invoke a generated API tool.\n\n## gemini-cli\n\n**Official reference:** https://geminicli.com/docs/tools/mcp-server/\n**Retrieved:** 2026-07-28\n\nGemini CLI uses top-level `mcpServers` in explicit project or global `settings.json`. The plan records scope and no host/project secret values are read.\n\n**Verification:** reread/schema-check `settings.json`, restart Gemini CLI, and use its MCP inspection flow to confirm local discovery. Failed discovery rolls back this target only.\n\n## opencode\n\n**Official reference:** https://opencode.ai/docs/mcp-servers/\n**Retrieved:** 2026-07-28\n\nOpenCode supports local and remote MCP servers. `~/.config/opencode/opencode.json` is a **Linux/XDG example**, not a universal path. Native local servers are under `mcp.servers` with a command array. Prefer documented `opencode mcp add`; otherwise mutate only valid non-symlink JSON and fail closed if format differs.\n\n**Verification:** use OpenCode MCP server-management inspection after registration plus reread/schema-check of direct JSON writes. Confirm discovery without calling upstream tools.\n\n## Portable entry shape\n\n```json\n{\n  \"mcpServers\": {\n    \"example-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/generated-project/dist/index.js\"],\n      \"cwd\": \"/absolute/generated-project\"\n    }\n  }\n}\n```\n\nRequired environment variables are names only; users provide values outside generated artifacts and agent configuration.\n\nFile v0.2.2:references/type-mcp-runtime.md\n\n# TypeMCP Runtime Contract\n\nGenerated projects use the reviewed public npm package:\n\n```json\n\"@theorvane/type-mcp\": \"0.2.0\"\n```\n\n## Allowed public API\n\nGenerated TypeScript uses only these public exports:\n\n- `@McpServer`\n- `@McpTool`\n- `createMcpServer`\n- `startStdioServer`\n- `zod`\n- an explicit `InstanceResolver`\n\n`createMcpServer` and `startStdioServer` are asynchronous and must be awaited. The package uses TC39 standard decorators: generated `tsconfig.json` must not enable legacy `experimentalDecorators` or `emitDecoratorMetadata`.\n\n`@McpTool` requires an `input` Zod object. Generated code pins Zod v4 (`^4.4.3`) because that is the compatible public runtime contract for `@theorvane/type-mcp@0.2.0`.\n\n## Prohibited runtime boundaries\n\nNever generate or publish any of the following:\n\n- copied TypeMCP source code;\n- `file:`, `git:`, `link:`, or `portal:` dependencies;\n- imports from private, undocumented, or unavailable TypeMCP APIs;\n- local TypeMCP checkouts as a generated-project dependency.\n\nBefore generated lifecycle scripts run, contained verification inspects dependency metadata and the generated `package-lock.json`, then runs `npm ci --ignore-scripts` in a fresh isolated workspace with inherited npm proxy configuration disabled. It then typechecks, tests, builds, and executes a local stdio smoke test against a mock upstream. Use a host container/VM/sandbox when the dependency graph is untrusted.\n\nFile v0.2.2:skill-card.md\n\n## Description: <br>\nUse when turning supplied API sources into a safe TypeMCP project. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[sjungwon03](https://clawhub.ai/user/sjungwon03) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and engineers use this skill to convert supplied local OpenAPI, Swagger UI, Markdown, or HTML API references into a TypeMCP stdio project with manifest review, generation approval, and optional agent installation. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Local code generation plus optional generated-project verification can install npm dependencies and run local build or test commands. <br>\nMitigation: Use a fresh empty output directory and run npm verification in a container, VM, or equivalent host sandbox when dependencies are untrusted. <br>\nRisk: Optional MCP agent installation can modify local agent configuration files. <br>\nMitigation: Keep project-only unless agent installation is explicitly needed, and review every config path, command, argument, environment-variable name, and backup path before approving installation. <br>\nRisk: Generated API tools may include mutating operations. <br>\nMitigation: Leave protected operations disabled unless exact operation IDs are explicitly approved before request construction. <br>\n\n\n## Reference(s): <br>\n- [TypeMCP Runtime Contract](references/type-mcp-runtime.md) <br>\n- [Agent MCP Installation Reference](references/agent-mcp-installation.md) <br>\n- [Hermes MCP Documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) <br>\n- [Claude Code MCP Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) <br>\n- [Codex CLI Reference](https://developers.openai.com/codex/cli/reference) <br>\n- [Cursor MCP Documentation](https://cursor.com/docs/mcp) <br>\n- [VS Code MCP Servers Documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers) <br>\n- [Gemini CLI MCP Server Documentation](https://geminicli.com/docs/tools/mcp-server/) <br>\n- [OpenCode MCP Servers Documentation](https://opencode.ai/docs/mcp-servers/) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration] <br>\n**Output Format:** [Markdown guidance with generated TypeScript project files, JSON manifests, and MCP configuration snippets.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Generation is gated by manifest review and single-use approval; optional agent installation uses a separate reviewed plan.] <br>\n\n## Skill Version(s): <br>\n0.2.2 (source: frontmatter and server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v0.2.2:tests/fixtures/api-reference.md\n\n# Petstore API Reference\n\n## Authentication\n\nAll requests require an `api_key` header.\n\n## Endpoints\n\n### List Pets\n\n    GET /pets\n\nReturns all pets.\n\n### Get Pet by ID\n\n    GET /pets/{petId}\n\nReturns a single pet.\n\n### Create Pet\n\n    POST /pets\n\nCreates a new pet. Request body:\n\n```json\n{\"name\": \"Buddy\", \"status\": \"available\"}\n```\n\n### Delete Pet\n\n    DELETE /pets/{petId}\n\nDeletes a pet by ID.\n\n## Notes\n\nThe API rate limit is 100 requests per minute.\nContact support@example.com for access issues.\n\nFile v0.2.2:tests/fixtures/petstore.openapi.json\n\n{\n  \"openapi\": \"3.0.3\",\n  \"info\": {\"title\": \"Pet store\", \"version\": \"1.0.0\"},\n  \"servers\": [{\"url\": \"https://api.example.test/v1?api_key=fixture-secret-query\"}],\n  \"paths\": {\n    \"/pets/{petId}\": {\n      \"get\": {\n        \"operationId\": \"getPet\",\n        \"parameters\": [\n          {\"name\": \"petId\", \"in\": \"path\", \"required\": true, \"schema\": {\"type\": \"string\"}},\n          {\"name\": \"api_key\", \"in\": \"query\", \"schema\": {\"type\": \"string\", \"default\": \"fixture-secret-query\"}}\n        ],\n        \"responses\": {\"200\": {\"description\": \"A pet\"}}\n      }\n    },\n    \"/pets\": {\n      \"post\": {\n        \"operationId\": \"createPet\",\n        \"requestBody\": {\"required\": true, \"content\": {\"application/json\": {\"schema\": {\"type\": \"object\"}}}},\n        \"responses\": {\"201\": {\"description\": \"Created\"}}\n      }\n    }\n  }\n}\n\nFile v0.2.2:tests/fixtures/petstore.swagger.yaml\n\nswagger: \"2.0\"\ninfo:\n  title: Pet store\n  version: \"1.0.0\"\nhost: api.example.test\nbasePath: /v1\nschemes:\n  - https\npaths:\n  /pets/{petId}:\n    get:\n      operationId: getPet\n      parameters:\n        - name: petId\n          in: path\n          required: true\n          type: string\n      responses:\n        \"200\":\n          description: A pet\n  /pets:\n    post:\n      operationId: createPet\n      parameters:\n        - name: body\n          in: body\n          required: true\n          schema:\n            type: object\n      responses:\n        \"201\":\n          description: Created\n\nFile v0.2.2:requirements.txt\n\n# Required by `scripts/intake.py` for safe local YAML parsing.\nPyYAML==6.0.3\n\nArchive v0.2.1: 40 files, 84036 bytes\n\nFiles: references/type-mcp-runtime.md (1425b), requirements.txt (77b), scripts/api_to_typemcp.py (10834b), scripts/approval.py (6293b), scripts/documents.py (3785b), scripts/intake.py (7300b), scripts/manifest.py (762b), scripts/policy.py (1543b), scripts/render.py (16514b), scripts/structured_specs.py (16750b), scripts/swagger_ui.py (2075b), scripts/verify_generated.py (11452b), skill-card.md (2612b), SKILL.md (6616b), templates/typescript-stdio/package-lock.json.tmpl (87670b), templates/typescript-stdio/package.json.tmpl (463b), templates/typescript-stdio/README.md.tmpl (962b), templates/typescript-stdio/src/api-client.ts.tmpl (1751b), templates/typescript-stdio/src/index.ts.tmpl (255b), templates/typescript-stdio/src/policy.ts.tmpl (1665b), templates/typescript-stdio/tsconfig.json.tmpl (278b), tests/fixtures/api-reference.html (632b), tests/fixtures/api-reference.md (504b), tests/fixtures/mock_upstream.py (3915b), tests/fixtures/petstore.openapi.json (804b), tests/fixtures/petstore.swagger.yaml (579b), tests/fixtures/swagger-ui.html (434b), tests/test_approval.py (6165b), tests/test_document_intake.py (4595b), tests/test_documents.py (6012b), tests/test_engine_cli.py (7201b), tests/test_generated_project_e2e.py (9879b), tests/test_generated_project_static.py (7946b), tests/test_manifest.py (14717b), tests/test_output_safety.py (9128b), tests/test_policy.py (1512b), tests/test_render.py (10488b), tests/test_swagger_ui.py (3218b), tests/test_verify_generated_security.py (2102b), _meta.json (133b)\n\nFile v0.2.1:SKILL.md\n\n---\nname: api-to-typemcp\ndescription: Use when turning supplied API sources into a safe TypeMCP project.\nversion: 0.2.1\ncategory: integration\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [mcp, api, openapi, swagger, code-generation, type-mcp]\n    related_skills: []\n  openclaw:\n    requires:\n      bins: [python3, node, npm]\n    envVars:\n      - name: TYPE_MCP_APPROVAL_STATE_DIR\n        required: false\n        description: Isolated directory for single-use generation approvals.\n      - name: TYPE_MCP_BASE_URL\n        required: false\n        description: Local test upstream used only by contained verification.\n---\n\n# API to TypeMCP\n\n## Overview\n\nThis released skill is a complete, bundled generator delivery unit. Its **bundled skill engine** is in `scripts/`, its controlled TypeScript output templates are in `templates/`, and its public TypeMCP runtime constraints are in [references/type-mcp-runtime.md](references/type-mcp-runtime.md).\n\nGenerated projects depend only on published `@theorvane/type-mcp@0.2.0`; they never copy TypeMCP source or use local, `file:`, `git:`, `link:`, or private runtime APIs.\n\n## When to use\n\nUse this skill with a **supplied local** OpenAPI 3.x / Swagger 2.0 JSON/YAML file, supplied Swagger UI HTML, or supplied Markdown/HTML API reference. Do not use it to crawl a bare origin, infer undocumented operations, make mutating calls by default, or publish without explicit final confirmation.\n\n## Execution permissions and containment boundary\n\nThe engine reads only the user-supplied source and files bundled with this skill. It writes only the caller-created output directory and the optional `TYPE_MCP_APPROVAL_STATE_DIR`; it never modifies an upstream API or publishes a repository without the separate explicit gates below.\n\nThe engine invokes `python3`. Optional generated-project verification additionally invokes `npm` and `node`, uses a fresh temporary workspace, passes a credential-scrubbed environment, disables inherited npm proxy settings and lifecycle scripts, and installs exactly the generated `package-lock.json` graph with `npm ci`. That install requires outbound access to the npm registry; the generator itself performs no network fetch or crawling, and the smoke test targets only a caller-provided local test upstream.\n\nThis verifier is **process containment**, not a claim of kernel or network isolation. Run it in a container, VM, or an equivalent host sandbox when the generated project or its dependency installation is untrusted.\n\n## Bundled engine workflow\n\nRun the engine through its installed skill-relative path. Set `SKILL_DIR` to the directory containing this `SKILL.md`; create a **controlled temporary output directory** yourself and keep it empty.\n\n```bash\nSKILL_DIR=\"/absolute/path/to/api-to-typemcp\"\nSOURCE=\"/absolute/path/to/supplied-openapi.json\"\nOUTPUT=\"$(mktemp -d -t api-to-typemcp-output.XXXXXX)\"\nSTATE=\"$(mktemp -d -t api-to-typemcp-state.XXXXXX)\"\nexport TYPE_MCP_APPROVAL_STATE_DIR=\"$STATE\"\n\n# 1. Inspect and build the exact secret-free manifest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" inspect --file \"$SOURCE\" --json\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest --file \"$SOURCE\" --json > manifest.json\nDIGEST=\"$(python3 -c 'import json; print(json.load(open(\"manifest.json\"))[\"digest\"])')\"\n\n# 2. Review the manifest, then explicitly approve precisely that digest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" approve \\\n  --file \"$SOURCE\" --manifest-digest \"$DIGEST\"\n\n# 3. Render only after approval, with an exact digest confirmation.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" generate \\\n  --file \"$SOURCE\" --output \"$OUTPUT\" \\\n  --confirm-manifest-digest \"$DIGEST\"\n```\n\nFor supplied Markdown or HTML, add an explicit origin; no page is fetched or crawled:\n\n```bash\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest \\\n  --file \"/absolute/path/to/reference.md\" \\\n  --base-url \"https://api.example.test\" --json\n```\n\nSwagger UI discovery is performed by `inspect` in-memory and returns only an explicit configured spec reference. The user must separately supply that structured spec; do not fetch it automatically.\n\n## Mandatory safety gates\n\n1. **Manifest first.** Treat every source as untrusted. Review canonical secret-free manifest data before generation.\n2. **Receipt gate.** `approve` issues a HMAC-protected, digest-bound, single-use receipt. A changed, expired, tampered, or already-consumed receipt stops `generate`.\n3. **Output gate.** The output directory must already exist and be empty unless `--replace` is explicitly supplied. Symlinks and `..` traversal are rejected.\n4. **Runtime policy.** `GET`/`HEAD`/`OPTIONS` are read operations. `POST`/`PUT`/`PATCH`/`DELETE` are protected writes and require exact known IDs in `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS` **before URL, query, headers, body, authentication, or dispatch**. Unknown methods deny.\n5. **Containment.** Verify generated projects in a scrubbed temporary workspace, after package inspection and with a generated lockfile. Use `npm ci --ignore-scripts` with inherited proxy settings disabled, then typecheck, test, build, and run a local MCP stdio smoke test. Use a container, VM, or equivalent host sandbox when the project or dependency graph is untrusted.\n6. **Publication.** **Immediately before GitHub publication**, record owner/org, repository name, visibility, and source branch. Resolve the actual checked-out/ref-to-publish branch and stop unless it exactly equals the recorded source branch. Ask for explicit user confirmation before the publication action.\n\n## Runtime compatibility\n\nRead [references/type-mcp-runtime.md](references/type-mcp-runtime.md) before modifying generated TypeScript. Use only `McpServer`, `McpTool`, `createMcpServer`, `startStdioServer`, `zod`, and an explicit `InstanceResolver` from the public contract.\n\n## Verification checklist\n\n- [ ] Source is supplied explicitly; no origin crawling occurred.\n- [ ] Manifest is secret-free, evidence-backed, and canonically digested.\n- [ ] Digest approval and a valid single-use receipt precede generation.\n- [ ] Output target passed the empty/replace and traversal/symlink safety gates.\n- [ ] Protected writes are authorized before request construction.\n- [ ] Generated project uses published `@theorvane/type-mcp@0.2.0` only and includes a reviewed `package-lock.json`.\n- [ ] Contained `npm ci --ignore-scripts`/typecheck/test/build/MCP smoke passes; external sandboxing is used for untrusted dependency installation.\n- [ ] Immediately before GitHub publication, user confirms owner/name/visibility/source branch and the resolved branch matches.\n\nFile v0.2.1:_meta.json\n\n{\n  \"ownerId\": \"kn701ftcm7pjm5537hh2jnv7y18b5q10\",\n  \"slug\": \"api-to-typemcp\",\n  \"version\": \"0.2.1\",\n  \"publishedAt\": 1785239303964\n}\n\nFile v0.2.1:references/type-mcp-runtime.md\n\n# TypeMCP Runtime Contract\n\nGenerated projects use the reviewed public npm package:\n\n```json\n\"@theorvane/type-mcp\": \"0.2.0\"\n```\n\n## Allowed public API\n\nGenerated TypeScript uses only these public exports:\n\n- `@McpServer`\n- `@McpTool`\n- `createMcpServer`\n- `startStdioServer`\n- `zod`\n- an explicit `InstanceResolver`\n\n`createMcpServer` and `startStdioServer` are asynchronous and must be awaited. The package uses TC39 standard decorators: generated `tsconfig.json` must not enable legacy `experimentalDecorators` or `emitDecoratorMetadata`.\n\n`@McpTool` requires an `input` Zod object. Generated code pins Zod v4 (`^4.4.3`) because that is the compatible public runtime contract for `@theorvane/type-mcp@0.2.0`.\n\n## Prohibited runtime boundaries\n\nNever generate or publish any of the following:\n\n- copied TypeMCP source code;\n- `file:`, `git:`, `link:`, or `portal:` dependencies;\n- imports from private, undocumented, or unavailable TypeMCP APIs;\n- local TypeMCP checkouts as a generated-project dependency.\n\nBefore generated lifecycle scripts run, contained verification inspects dependency metadata and the generated `package-lock.json`, then runs `npm ci --ignore-scripts` in a fresh isolated workspace with inherited npm proxy configuration disabled. It then typechecks, tests, builds, and executes a local stdio smoke test against a mock upstream. Use a host container/VM/sandbox when the dependency graph is untrusted.\n\nFile v0.2.1:skill-card.md\n\n## Description: <br>\nUse when turning supplied API sources into a safe TypeMCP project. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[sjungwon03](https://clawhub.ai/user/sjungwon03) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and engineers use this skill to convert supplied local OpenAPI, Swagger, Swagger UI, Markdown, or HTML API references into a TypeMCP project with manifest approval, output, runtime policy, and verification gates. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The generator writes to a local output directory and may leave partial output if generation fails. <br>\nMitigation: Use a caller-created empty temporary output directory, keep the output gate enabled, and review generated files before reuse. <br>\nRisk: Optional verification installs npm packages from the public registry and is process containment rather than full system isolation. <br>\nMitigation: Run verification in a container, VM, or equivalent host sandbox when specs or dependencies are untrusted. <br>\nRisk: Generated protected-write tools can call mutating API operations if explicitly enabled. <br>\nMitigation: Review generated protected-write tools before setting TYPE_MCP_ALLOW_PROTECTED_OPERATIONS and allow only exact known operation IDs. <br>\nRisk: Server security guidance notes the package appears to be missing .env.example.tmpl, so generation may fail until fixed or republished. <br>\nMitigation: Validate generation in a disposable workspace before relying on this release. <br>\n\n\n## Reference(s): <br>\n- [TypeMCP Runtime Contract](references/type-mcp-runtime.md) <br>\n- [ClawHub Release Page](https://clawhub.ai/sjungwon03/skills/api-to-typemcp) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Code, Files, Shell commands, Configuration instructions, Guidance] <br>\n**Output Format:** [Markdown guidance plus generated TypeScript, JSON, npm, and configuration files] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Generated projects use a published TypeMCP runtime, include a package-lock.json, and are intended to be reviewed and verified before publication.] <br>\n\n## Skill Version(s): <br>\n0.2.1 (source: SKILL.md frontmatter and server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v0.2.1:tests/fixtures/api-reference.md\n\n# Petstore API Reference\n\n## Authentication\n\nAll requests require an `api_key` header.\n\n## Endpoints\n\n### List Pets\n\n    GET /pets\n\nReturns all pets.\n\n### Get Pet by ID\n\n    GET /pets/{petId}\n\nReturns a single pet.\n\n### Create Pet\n\n    POST /pets\n\nCreates a new pet. Request body:\n\n```json\n{\"name\": \"Buddy\", \"status\": \"available\"}\n```\n\n### Delete Pet\n\n    DELETE /pets/{petId}\n\nDeletes a pet by ID.\n\n## Notes\n\nThe API rate limit is 100 requests per minute.\nContact support@example.com for access issues.\n\nFile v0.2.1:tests/fixtures/petstore.openapi.json\n\n{\n  \"openapi\": \"3.0.3\",\n  \"info\": {\"title\": \"Pet store\", \"version\": \"1.0.0\"},\n  \"servers\": [{\"url\": \"https://api.example.test/v1?api_key=fixture-secret-query\"}],\n  \"paths\": {\n    \"/pets/{petId}\": {\n      \"get\": {\n        \"operationId\": \"getPet\",\n        \"parameters\": [\n          {\"name\": \"petId\", \"in\": \"path\", \"required\": true, \"schema\": {\"type\": \"string\"}},\n          {\"name\": \"api_key\", \"in\": \"query\", \"schema\": {\"type\": \"string\", \"default\": \"fixture-secret-query\"}}\n        ],\n        \"responses\": {\"200\": {\"description\": \"A pet\"}}\n      }\n    },\n    \"/pets\": {\n      \"post\": {\n        \"operationId\": \"createPet\",\n        \"requestBody\": {\"required\": true, \"content\": {\"application/json\": {\"schema\": {\"type\": \"object\"}}}},\n        \"responses\": {\"201\": {\"description\": \"Created\"}}\n      }\n    }\n  }\n}\n\nFile v0.2.1:tests/fixtures/petstore.swagger.yaml\n\nswagger: \"2.0\"\ninfo:\n  title: Pet store\n  version: \"1.0.0\"\nhost: api.example.test\nbasePath: /v1\nschemes:\n  - https\npaths:\n  /pets/{petId}:\n    get:\n      operationId: getPet\n      parameters:\n        - name: petId\n          in: path\n          required: true\n          type: string\n      responses:\n        \"200\":\n          description: A pet\n  /pets:\n    post:\n      operationId: createPet\n      parameters:\n        - name: body\n          in: body\n          required: true\n          schema:\n            type: object\n      responses:\n        \"201\":\n          description: Created\n\nFile v0.2.1:requirements.txt\n\n# Required by `scripts/intake.py` for safe local YAML parsing.\nPyYAML==6.0.3\n\nArchive v0.2.0: 38 files, 60303 bytes\n\nFiles: references/type-mcp-runtime.md (1429b), requirements.txt (77b), scripts/api_to_typemcp.py (10834b), scripts/approval.py (6293b), scripts/documents.py (3785b), scripts/intake.py (7300b), scripts/manifest.py (762b), scripts/policy.py (1543b), scripts/render.py (16244b), scripts/structured_specs.py (16750b), scripts/swagger_ui.py (2075b), scripts/verify_generated.py (10959b), skill-card.md (2704b), SKILL.md (4914b), templates/typescript-stdio/package.json.tmpl (405b), templates/typescript-stdio/README.md.tmpl (962b), templates/typescript-stdio/src/api-client.ts.tmpl (1663b), templates/typescript-stdio/src/index.ts.tmpl (255b), templates/typescript-stdio/src/policy.ts.tmpl (1665b), templates/typescript-stdio/tsconfig.json.tmpl (278b), tests/fixtures/api-reference.html (632b), tests/fixtures/api-reference.md (504b), tests/fixtures/mock_upstream.py (3915b), tests/fixtures/petstore.openapi.json (804b), tests/fixtures/petstore.swagger.yaml (579b), tests/fixtures/swagger-ui.html (434b), tests/test_approval.py (6165b), tests/test_document_intake.py (4595b), tests/test_documents.py (6012b), tests/test_engine_cli.py (7201b), tests/test_generated_project_e2e.py (9884b), tests/test_generated_project_static.py (7946b), tests/test_manifest.py (14717b), tests/test_output_safety.py (9128b), tests/test_policy.py (1512b), tests/test_render.py (9853b), tests/test_swagger_ui.py (3218b), _meta.json (133b)\n\nFile v0.2.0:SKILL.md\n\n---\nname: api-to-typemcp\ndescription: Use when turning supplied API sources into a safe TypeMCP project.\nversion: 0.2.0\ncategory: integration\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [mcp, api, openapi, swagger, code-generation, type-mcp]\n    related_skills: []\n---\n\n# API to TypeMCP\n\n## Overview\n\nThis released skill is a complete, bundled generator delivery unit. Its **bundled skill engine** is in `scripts/`, its controlled TypeScript output templates are in `templates/`, and its public TypeMCP runtime constraints are in [references/type-mcp-runtime.md](references/type-mcp-runtime.md).\n\nGenerated projects depend only on published `@theorvane/type-mcp@0.2.0`; they never copy TypeMCP source or use local, `file:`, `git:`, `link:`, or private runtime APIs.\n\n## When to use\n\nUse this skill with a **supplied local** OpenAPI 3.x / Swagger 2.0 JSON/YAML file, supplied Swagger UI HTML, or supplied Markdown/HTML API reference. Do not use it to crawl a bare origin, infer undocumented operations, make mutating calls by default, or publish without explicit final confirmation.\n\n## Bundled engine workflow\n\nRun the engine through its installed skill-relative path. Set `SKILL_DIR` to the directory containing this `SKILL.md`; create a **controlled temporary output directory** yourself and keep it empty.\n\n```bash\nSKILL_DIR=\"/absolute/path/to/api-to-typemcp\"\nSOURCE=\"/absolute/path/to/supplied-openapi.json\"\nOUTPUT=\"$(mktemp -d -t api-to-typemcp-output.XXXXXX)\"\nSTATE=\"$(mktemp -d -t api-to-typemcp-state.XXXXXX)\"\nexport TYPE_MCP_APPROVAL_STATE_DIR=\"$STATE\"\n\n# 1. Inspect and build the exact secret-free manifest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" inspect --file \"$SOURCE\" --json\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest --file \"$SOURCE\" --json > manifest.json\nDIGEST=\"$(python3 -c 'import json; print(json.load(open(\"manifest.json\"))[\"digest\"])')\"\n\n# 2. Review the manifest, then explicitly approve precisely that digest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" approve \\\n  --file \"$SOURCE\" --manifest-digest \"$DIGEST\"\n\n# 3. Render only after approval, with an exact digest confirmation.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" generate \\\n  --file \"$SOURCE\" --output \"$OUTPUT\" \\\n  --confirm-manifest-digest \"$DIGEST\"\n```\n\nFor supplied Markdown or HTML, add an explicit origin; no page is fetched or crawled:\n\n```bash\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest \\\n  --file \"/absolute/path/to/reference.md\" \\\n  --base-url \"https://api.example.test\" --json\n```\n\nSwagger UI discovery is performed by `inspect` in-memory and returns only an explicit configured spec reference. The user must separately supply that structured spec; do not fetch it automatically.\n\n## Mandatory safety gates\n\n1. **Manifest first.** Treat every source as untrusted. Review canonical secret-free manifest data before generation.\n2. **Receipt gate.** `approve` issues a HMAC-protected, digest-bound, single-use receipt. A changed, expired, tampered, or already-consumed receipt stops `generate`.\n3. **Output gate.** The output directory must already exist and be empty unless `--replace` is explicitly supplied. Symlinks and `..` traversal are rejected.\n4. **Runtime policy.** `GET`/`HEAD`/`OPTIONS` are read operations. `POST`/`PUT`/`PATCH`/`DELETE` are protected writes and require exact known IDs in `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS` **before URL, query, headers, body, authentication, or dispatch**. Unknown methods deny.\n5. **Containment.** Verify generated projects in a scrubbed temporary workspace, with no inherited credentials, dependency inspection, no-lifecycle installation, typecheck, tests, build, and local MCP stdio smoke.\n6. **Publication.** **Immediately before GitHub publication**, record owner/org, repository name, visibility, and source branch. Resolve the actual checked-out/ref-to-publish branch and stop unless it exactly equals the recorded source branch. Ask for explicit user confirmation before the publication action.\n\n## Runtime compatibility\n\nRead [references/type-mcp-runtime.md](references/type-mcp-runtime.md) before modifying generated TypeScript. Use only `McpServer`, `McpTool`, `createMcpServer`, `startStdioServer`, `zod`, and an explicit `InstanceResolver` from the public contract.\n\n## Verification checklist\n\n- [ ] Source is supplied explicitly; no origin crawling occurred.\n- [ ] Manifest is secret-free, evidence-backed, and canonically digested.\n- [ ] Digest approval and a valid single-use receipt precede generation.\n- [ ] Output target passed the empty/replace and traversal/symlink safety gates.\n- [ ] Protected writes are authorized before request construction.\n- [ ] Generated project uses published `@theorvane/type-mcp@0.2.0` only.\n- [ ] Contained install/typecheck/test/build/MCP smoke passes.\n- [ ] Immediately before GitHub publication, user confirms owner/name/visibility/source branch and the resolved branch matches.\n\nFile v0.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn701ftcm7pjm5537hh2jnv7y18b5q10\",\n  \"slug\": \"api-to-typemcp\",\n  \"version\": \"0.2.0\",\n  \"publishedAt\": 1785224225339\n}\n\nFile v0.2.0:references/type-mcp-runtime.md\n\n# TypeMCP Runtime Contract\n\nGenerated projects use the reviewed public npm package:\n\n```json\n\"@theorvane/type-mcp\": \"0.2.0\"\n```\n\n## Allowed public API\n\nGenerated TypeScript uses only these public exports:\n\n- `@McpServer`\n- `@McpTool`\n- `createMcpServer`\n- `startStdioServer`\n- `zod`\n- an explicit `InstanceResolver`\n\n`createMcpServer` and `startStdioServer` are asynchronous and must be awaited. The package uses TC39 standard decorators: generated `tsconfig.json` must not enable legacy `experimentalDecorators` or `emitDecoratorMetadata`.\n\n`@McpTool` requires an `input` Zod object. Generated code pins Zod v4 (`^4.4.3`) because that is the compatible public runtime contract for `@theorvane/type-mcp@0.2.0`.\n\n## Prohibited runtime boundaries\n\nNever generate or publish any of the following:\n\n- copied TypeMCP source code;\n- `file:`, `git:`, `link:`, or `portal:` dependencies;\n- imports from private, undocumented, or unavailable TypeMCP APIs;\n- local TypeMCP checkouts as a generated-project dependency.\n\nBefore generated lifecycle scripts run, contained verification inspects dependency metadata and runs `npm install --ignore-scripts` in a fresh isolated workspace. Generated projects currently do not ship a lockfile, so this establishes a fresh no-lifecycle install rather than claiming a lockfile-pinned `npm ci` install. It then typechecks, tests, builds, and executes a local stdio smoke test against a mock upstream.\n\nFile v0.2.0:skill-card.md\n\n## Description: <br>\nTurns supplied local API sources into a TypeMCP project with manifest review, digest-bound approval, and generated-project verification gates. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[sjungwon03](https://clawhub.ai/user/sjungwon03) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and engineers use this skill to turn supplied local OpenAPI, Swagger, Swagger UI, Markdown, or HTML API references into a TypeMCP stdio MCP server project. It is intended for workflows where the generated manifest is reviewed and explicitly approved before code generation. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Generated projects install and execute package dependencies during verification, and the security evidence flags limited containment plus inconsistent dependency disclosures. <br>\nMitigation: Review generated dependency ranges, add a lockfile or audit step where practical, and run verification in a container or similarly isolated workspace. <br>\nRisk: API specifications or reference documents may contain secrets or sensitive operational details. <br>\nMitigation: Do not place secrets in supplied specs or documentation fields; review the secret-free manifest before approval and generation. <br>\nRisk: Generated MCP tools can represent mutating upstream API operations. <br>\nMitigation: Enable protected-write operations only by exact operation ID when mutation is intended, and keep the default deny behavior for unreviewed write operations. <br>\nRisk: A generated project may reflect incomplete or incorrect API documentation. <br>\nMitigation: Inspect the manifest first, confirm the canonical digest, and regenerate only after the reviewed manifest matches the intended local source. <br>\n\n\n## Reference(s): <br>\n- [TypeMCP Runtime Contract](references/type-mcp-runtime.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration] <br>\n**Output Format:** [Generated TypeScript project files, JSON manifests, Markdown guidance, and shell commands] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Generated projects target local stdio MCP use and include policy tests plus a secret-free manifest copy.] <br>\n\n## Skill Version(s): <br>\n0.2.0 (source: server release and skill frontmatter) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v0.2.0:tests/fixtures/api-reference.md\n\n# Petstore API Reference\n\n## Authentication\n\nAll requests require an `api_key` header.\n\n## Endpoints\n\n### List Pets\n\n    GET /pets\n\nReturns all pets.\n\n### Get Pet by ID\n\n    GET /pets/{petId}\n\nReturns a single pet.\n\n### Create Pet\n\n    POST /pets\n\nCreates a new pet. Request body:\n\n```json\n{\"name\": \"Buddy\", \"status\": \"available\"}\n```\n\n### Delete Pet\n\n    DELETE /pets/{petId}\n\nDeletes a pet by ID.\n\n## Notes\n\nThe API rate limit is 100 requests per minute.\nContact support@example.com for access issues.\n\nFile v0.2.0:tests/fixtures/petstore.openapi.json\n\n{\n  \"openapi\": \"3.0.3\",\n  \"info\": {\"title\": \"Pet store\", \"version\": \"1.0.0\"},\n  \"servers\": [{\"url\": \"https://api.example.test/v1?api_key=fixture-secret-query\"}],\n  \"paths\": {\n    \"/pets/{petId}\": {\n      \"get\": {\n        \"operationId\": \"getPet\",\n        \"parameters\": [\n          {\"name\": \"petId\", \"in\": \"path\", \"required\": true, \"schema\": {\"type\": \"string\"}},\n          {\"name\": \"api_key\", \"in\": \"query\", \"schema\": {\"type\": \"string\", \"default\": \"fixture-secret-query\"}}\n        ],\n        \"responses\": {\"200\": {\"description\": \"A pet\"}}\n      }\n    },\n    \"/pets\": {\n      \"post\": {\n        \"operationId\": \"createPet\",\n        \"requestBody\": {\"required\": true, \"content\": {\"application/json\": {\"schema\": {\"type\": \"object\"}}}},\n        \"responses\": {\"201\": {\"description\": \"Created\"}}\n      }\n    }\n  }\n}\n\nFile v0.2.0:tests/fixtures/petstore.swagger.yaml\n\nswagger: \"2.0\"\ninfo:\n  title: Pet store\n  version: \"1.0.0\"\nhost: api.example.test\nbasePath: /v1\nschemes:\n  - https\npaths:\n  /pets/{petId}:\n    get:\n      operationId: getPet\n      parameters:\n        - name: petId\n          in: path\n          required: true\n          type: string\n      responses:\n        \"200\":\n          description: A pet\n  /pets:\n    post:\n      operationId: createPet\n      parameters:\n        - name: body\n          in: body\n          required: true\n          schema:\n            type: object\n      responses:\n        \"201\":\n          description: Created\n\nFile v0.2.0:requirements.txt\n\n# Required by `scripts/intake.py` for safe local YAML parsing.\nPyYAML==6.0.3\n\nArchive v0.1.4: 3 files, 5915 bytes\n\nFiles: skill-card.md (2556b), SKILL.md (10061b), _meta.json (133b)\n\nFile v0.1.4:SKILL.md\n\n---\nname: api-to-typemcp\ndescription: Use when a user wants to turn an API URL, OpenAPI/Swagger file or link, Swagger UI, or Markdown/HTML API documentation into a standalone TypeMCP MCP project through the type-mcp-api-cli.\nversion: 0.1.4\ncategory: integration\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [mcp, api, openapi, swagger, code-generation, type-mcp]\n    related_skills: []\n---\n\n# API to TypeMCP\n\n## Overview\n\nThis skill orchestrates the independently versioned `packages/type-mcp-api-cli` package in this workspace (or a future trusted npm release of that same package). It does not parse specifications, extract endpoints, create TypeScript templates, or substitute its own generator. The CLI is the deterministic engine; this skill is the approval, safety, verification, and publication layer.\n\nThe target is a normal standalone TypeScript MCP repository whose runtime dependency is npm `type-mcp`.\n\n## Current availability\n\nThe skill is installed and its orchestration guidance is available, even while no compatible CLI release is supported. It can explain the required source, manifest-approval, safety, verification, and publication workflow; it must **not** install or execute a candidate CLI, generate a project, run generated code, or publish output until the compatibility policy explicitly enables a release.\n\nWhen a user requests generation while the policy lists no supported release, give this safe outcome:\n\n> `api-to-typemcp` is installed, but no supported `type-mcp-api-cli` release is available yet. Project generation is intentionally blocked by the compatibility policy; no CLI was installed or executed. A maintainer must update [the canonical CLI compatibility policy](https://github.com/Theorvane/type-mcp-api-agent-skill/blob/dev/docs/guides/cli-compatibility.md) only after a reviewed CLI npm release is available; then retry.\n\nDo not replace the CLI with an in-workspace, global, `PATH`, or user-provided executable. The CLI release policy—not skill installation—controls whether generation may begin.\n\n## When to use\n\nUse this skill when the user provides or asks to use:\n\n- an OpenAPI 3.x or Swagger 2.0 JSON/YAML URL or file;\n- a Swagger UI URL;\n- a Markdown/HTML API reference URL;\n- an API documentation URL plus a request to produce a maintainable TypeMCP MCP project.\n\nDo not use it for a bare bas...","readmeExcerpt":"Skill: api-to-typemcp Owner: sjungwon03 Summary: Use when turning supplied API sources into a safe TypeMCP project. Tags: latest:0.2.6 Version history: v0.2.6 | 2026-08-13T07:09:35.571Z | auto - Bumped version to 0.2.6. - Documentation updates in SKILL.md. - Removed unused file skill-card.md. - Minor changes and cleanup to scripts and test files. v0.2.5 | 2026-08-13T06:33:28.794Z | auto - Update version to 0.2.5. - D","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"SKILL_DIR=\"/absolute/path/to/api-to-typemcp\"\nSOURCE=\"/absolute/path/to/supplied-openapi.json\"\nOUTPUT=\"$(mktemp -d -t api-to-typemcp-output.XXXXXX)\"\nSTATE=\"$(mktemp -d -t api-to-typemcp-state.XXXXXX)\"\nexport TYPE_MCP_APPROVAL_STATE_DIR=\"$STATE\"\n\n# 1. Inspect and build the exact secret-free manifest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" inspect --file \"$SOURCE\" --json\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest --file \"$SOURCE\" --json > manifest.json\nDIGEST=\"$(python3 -c 'import json; print(json.load(open(\"manifest.json\"))[\"digest\"])')\"\n\n# 2. Review the manifest, then explicitly approve precisely that digest.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" approve \\\n  --file \"$SOURCE\" --manifest-digest \"$DIGEST\"\n\n# 3. Render only after approval, with an exact digest confirmation.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" generate \\\n  --file \"$SOURCE\" --output \"$OUTPUT\" \\\n  --confirm-manifest-digest \"$DIGEST\""},{"language":"bash","snippet":"python3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" manifest \\\n  --file \"/absolute/path/to/reference.md\" \\\n  --base-url \"https://api.example.test\" --json"},{"language":"bash","snippet":"# 1. The assistant asks: \"프로젝트만 생성할까요, 아니면 생성 후 에이전트에 탑재할까요?\"\n# 2. For install, inspect and show a secret-free plan before any config write.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-plan \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\"\n\n# 3. Review the preview, then explicitly issue the plan-bound one-time confirmation.\nPLAN_DIGEST=\"...shown by install-plan...\"\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-approve --plan-digest \"$PLAN_DIGEST\"\n\n# 4. Apply only the unchanged approved plan. Native registration is fail-closed\n#    unless the selected client already has a detected regular config file. Each\n#    target gets a 0600 backup; a later target failure restores earlier targets,\n#    and every write is reread/parsed before success is reported.\npython3 \"$SKILL_DIR/scripts/api_to_typemcp.py\" install-apply \\\n  --project \"$OUTPUT\" --targets \"cursor,gemini-cli\" --confirm-plan-digest \"$PLAN_DIGEST\""},{"language":"ts","snippet":"import { McpServer, McpTool } from \"@theorvane/type-mcp\";"},{"language":"ts","snippet":"import { McpServer, McpTool } from \"@theorvane/type-mcp/legacy\";"},{"language":"json","snippet":"{\n  \"mcpServers\": {\n    \"example-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/generated-project/dist/index.js\"],\n      \"cwd\": \"/absolute/generated-project\"\n    }\n  }\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: api-to-typemcp\ndescription: Use when turning supplied API sources into a safe TypeMCP project.\nversion: 0.2.6\ncategory: integration\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [mcp, api, openapi, swagger, code-generation, type-mcp]\n    related_skills: []\n  openclaw:\n    requires:\n      bins: [python3, node, npm]\n    envVars:\n      - name: TYPE_MCP_APPROVAL_STATE_DIR\n        required: false\n        description: Isolated directory for single-use generation approvals.\n      - name: TYPE_MCP_BASE_URL\n        required: false\n        description: Local test upstream used only by contained verification.\n---\n\n# API to TypeMCP\n\n## Overview\n\nThis released skill is a complete, bundled generator delivery unit. Its **bundled skill engine** is in `scripts/`, its controlled TypeScript output templates are in `templates/`, and its public TypeMCP runtime constraints are in [references/type-mcp-runtime.md](references/type-mcp-runtime.md).\n\nGenerated projects use the current published `@theorvane/type-mcp@0.3.2` release line and only its public package exports; they never copy TypeMCP source or use local, `file:`, `git:`, `link:`, or private runtime APIs. The npm registry `gitHead` and GitHub Release `v0.3.2` both resolve to `e75bcf6a81ef4df57301b6154a0088845020886f`.\n\n## When to use\n\nUse this skill with a **supplied local** OpenAPI 3.x / Swagger 2.0 JSON/YAML file, supplied Swagger UI HTML, or supplied Markdown/HTML API reference. Do not use it to crawl a bare origin, infer undocumented operations, make mutating calls by default, or publish without explicit final confirmation.\n\n## Execution permissions and containment boundary\n\nThe engine reads only the user-supplied source and files bundled with this skill. It writes only the caller-created output directory and the optional `TYPE_MCP_APPROVAL_STATE_DIR`; it never modifies an upstream API or publishes a repository without the separate explicit gates below.\n\nThe engine invokes `python3`. Optional generated-project verification additionally invokes `npm` and `node`, uses a fresh temporary workspace, passes a credential-scrubbed environment, disables inherited npm proxy settings and lifecycle scripts, and installs exactly the generated `package-lock.json` graph with `npm ci`. That install requires outbound access to the npm registry; the generator itself performs no network fetch or crawling, and the smoke test targets only a caller-provided local test upstream.\n\nThis verifier is **process containment**, not a claim of kernel or network isolation. Run it in a container, VM, or an equivalent host sandbox when the generated project or its dependency installation is untrusted.\n\n## Bundled engine workflow\n\nRun the engine through its installed skill-relative path. Set `SKILL_DIR` to the directory containing this `SKILL.md`; create a **controlled temporary output directory** yourself and keep it empty.\n\n```bash\nSKILL_DIR=\"/absolute/path/to/api-to-typemcp\"\nSOURCE=\"/absolute/path/to/supplied-openapi.json\"\nOUTPUT=\"$("},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn701ftcm7pjm5537hh2jnv7y18b5q10\",\n  \"slug\": \"api-to-typemcp\",\n  \"version\": \"0.2.6\",\n  \"publishedAt\": 1786604975571\n}"},{"path":"references/agent-mcp-installation.md","content":"# Agent MCP Installation Reference\n\n**Status:** implementation contract\n**Retrieved:** 2026-07-28\n\n`api-to-typemcp` produces local stdio MCP projects. Project-only generation is the default. Only after contained generated-project verification may the skill offer agent installation. Detection is read-only; installation requires selected targets, a displayed secret-free plan, and a separate final confirmation.\n\n## Global safety contract\n\n- The installer never reads `.env`, resolves credentials, or writes secret values into an agent config, plan, log, backup, or portable export. It displays environment-variable names only.\n- `generate` never scans or edits agent configuration.\n- Unknown, malformed, symlinked, fingerprint-changed, or unsupported targets fail closed.\n- Portable export does not modify an agent configuration. It writes a secret-free standard `mcpServers` snippet under generated-project `agent-install/`.\n- Per-target failure never implies another target is installed; a changed target has a same-directory backup and target-local rollback.\n- Protected writes remain fail-closed under `TYPE_MCP_ALLOW_PROTECTED_OPERATIONS`.\n\n## hermes\n\n**Official reference:** https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses only the documented `hermes mcp add <name> --command node --args <absolute-entry>` CLI path. The reviewed plan records the CLI-managed candidate path for operator visibility but the installer never reads or edits it directly. After registration, it runs `hermes mcp test <name>`; any non-zero result triggers `hermes mcp remove <name>` as compensating rollback. Hermes CLI currently exposes no cwd flag, so the generated absolute `dist/index.js` entrypoint is used and the plan reports the canonical project cwd for review. Environment variable values are never read or passed; users provide required values through their Hermes execution environment.\n\n## claude-code\n\n**Official reference:** https://docs.anthropic.com/en/docs/claude-code/mcp\n**Retrieved:** 2026-07-29\n\nNative registration uses the documented stdio form `claude mcp add --transport stdio <name> -- node <absolute-entry>`, where `--` separates Claude Code options from the server command. The installer never reads or edits Claude settings directly. It verifies registration using `claude mcp list` and requires the named server in successful output; a failed or absent discovery triggers `claude mcp remove <name>` as compensating rollback. Claude Code’s documented add form has no cwd argument, so the generated absolute entrypoint is used and the canonical project cwd remains plan-visible only. Environment variable values are never read or passed; users provide required values through their Claude Code execution environment.\n\n## codex\n\n**Official reference:** https://developers.openai.com/codex/cli/reference\n**Retrieved:** 2026-07-28\n\nPreferred path: `codex mcp add`, `codex mcp get`, and `codex mcp list`. Native entries u"},{"path":"references/type-mcp-runtime.md","content":"# TypeMCP Runtime Contract\n\nGenerated projects use the reviewed public npm package on the current 0.3.2 release line:\n\n```json\n\"@theorvane/type-mcp\": \"0.3.2\"\n```\n\n`@theorvane/type-mcp@0.3.2` is published with npm registry `gitHead` and GitHub Release `v0.3.2` both resolving to `e75bcf6a81ef4df57301b6154a0088845020886f`.\n\n## Allowed public API\n\nThe generator's default standard ESM path uses standard decorators from the public ESM/NodeNext entrypoint:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp\";\n```\n\nGenerated TypeScript uses only these public exports:\n\n- `@McpServer`\n- `@McpTool`\n- `createMcpServer`\n- `startStdioServer`\n- `zod`\n- an explicit `InstanceResolver`\n\n`createMcpServer` and `startStdioServer` are asynchronous and must be awaited. Standard decorators use TC39 semantics: generated `tsconfig.json` must not enable legacy `experimentalDecorators` or `emitDecoratorMetadata`.\n\n`@McpTool` requires an `input` Zod object. Generated code pins Zod v4 (`^4.4.3`) because that is the compatible public runtime contract for `@theorvane/type-mcp@0.3.2`.\n\n## Legacy decorator compatibility\n\nStandard and legacy decorators use distinct entrypoints and distinct decorator semantics. Legacy decorators are an opt-in public entrypoint for external CommonJS/Node16 projects that intentionally use TypeScript's legacy decorator mode; those projects must enable `experimentalDecorators` and import the decorators only from:\n\n```ts\nimport { McpServer, McpTool } from \"@theorvane/type-mcp/legacy\";\n```\n\nDo not mix this entrypoint with the standard ESM/NodeNext imports. The generator does not copy TypeMCP runtime source and must remain on its default standard ESM path; do not change its templates to legacy decorators or CommonJS.\n\n## Prohibited runtime boundaries\n\nNever generate or publish any of the following:\n\n- copied TypeMCP source code;\n- `file:`, `git:`, `link:`, or `portal:` dependencies;\n- imports from private, undocumented, or unavailable TypeMCP APIs;\n- local TypeMCP checkouts as a generated-project dependency.\n\nBefore generated lifecycle scripts run, contained verification inspects dependency metadata and the generated `package-lock.json`, then runs `npm ci --ignore-scripts` in a fresh isolated workspace with inherited npm proxy configuration disabled. It then typechecks, tests, builds, and executes a local stdio smoke test against a mock upstream. Use a host container/VM/sandbox when the dependency graph is untrusted."},{"path":"skill-card.md","content":"## Description:\n\nUse when turning supplied API sources into a safe TypeMCP project.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[sjungwon03](https://clawhub.ai/user/sjungwon03)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineers use this skill to convert supplied local OpenAPI, Swagger UI, or Markdown/HTML API references into a reviewed TypeMCP stdio MCP project. It is intended for project generation first, with optional agent installation only after verification and explicit confirmation.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A replace-generation path can overwrite files outside the chosen output folder.\n\nMitigation: Generate into a newly created empty directory, avoid --replace on directories that were not created and inspected for this run, and review paths before generation.\n\nRisk: Agent installation can modify persistent MCP client configuration.\n\nMitigation: Prefer project-only generation, review the secret-free installation plan, and require explicit confirmation before applying any agent configuration changes.\n\nRisk: Generated project verification installs npm dependencies and may be untrusted.\n\nMitigation: Run npm verification in a container, VM, or equivalent host sandbox for untrusted inputs.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/sjungwon03/skills/api-to-typemcp)\n- [TypeMCP Runtime Contract](references/type-mcp-runtime.md)\n- [Agent MCP Installation Reference](references/agent-mcp-installation.md)\n- [Hermes MCP documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)\n- [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp)\n- [Codex CLI MCP reference](https://developers.openai.com/codex/cli/reference)\n- [Cursor MCP documentation](https://cursor.com/docs/mcp)\n- [VS Code MCP servers documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance plus generated TypeScript project files and JSON/TOML MCP configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Generated projects use a pinned TypeMCP runtime line and may include optional agent installation plans or portable MCP server exports.]\n\n## Skill Version(s):\n\n0.2.6 (source: server release metadata and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1708,"uniquenessScore":42,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T16:10:22.180Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T16:10:22.180Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:57:35.435Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}