Skip to content

README.md

Latest commit

 

History

History
55 lines (41 loc) · 3.35 KB

README.md

File metadata and controls

55 lines (41 loc) · 3.35 KB
Raw

type-mcp-api-agent-skill

The published api-to-typemcp Hermes skill is the single delivery unit for API-to-TypeMCP generation. Its bundled skill engine accepts bounded supplied sources, produces approved secret-free manifests, and renders standalone TypeScript MCP projects that depend on the published @theorvane/type-mcp package.

Status

Tasks 1–7 of embedded-engine delivery are implemented on dev: structured OpenAPI/Swagger intake, bounded Swagger UI and Markdown/HTML evidence intake, digest-bound approval, controlled TypeScript rendering, contained project E2E verification, and runtime/package-contract documentation. Skill version publication remains a separate release-preparation change after this implementation sequence.

Safety contract

  • Manifest first: normalize and review a secret-free manifest before generation.
  • Bounded sources: accept supplied OpenAPI/Swagger files or explicit documentation only; never enumerate a bare API origin.
  • Secrets stay external: artifacts may contain environment-variable names and mappings, never values.
  • Protected writes fail closed: TYPE_MCP_ALLOW_PROTECTED_OPERATIONS must authorize an exact known operation ID before request construction.
  • Contained verification: inspect generated package.json and package-lock.json, use isolated npm ci --ignore-scripts with proxy settings disabled, and verify only in a fresh scrubbed workspace. Use a host container/VM/sandbox when the dependency graph is untrusted.
  • Publication is separate: immediately before publication, confirm owner/org, repository name, visibility, and source branch; verify the actual checked-out/ref-to-publish branch and stop unless it exactly equals the recorded source branch.

Install the released skill

Layout

.
├── skills/api-to-typemcp/       # published skill and bundled engine
│   ├── scripts/                 # deterministic intake, approval, rendering, verification
│   ├── templates/               # controlled TypeScript templates
│   └── references/              # published TypeMCP runtime contract
├── docs/                        # product, architecture, contract, and safety policy
├── .agents/                     # harness and documentation regression checks
└── .github/workflows/           # documentation and bundled-engine CI

Verification

python3 .agents/scripts/test_validate_docs.py
python3 .agents/scripts/test_workspace.py
python3 .agents/scripts/validate_docs.py
git diff --check

Canonical documentation

  • Product scope: docs/product/
  • Embedded-engine architecture: docs/architecture/
  • Manifest and generated API contracts: docs/api/
  • Safety, execution containment, and publication: docs/guides/
  • Approved plans: docs/planning/
  • Skill instructions and release artifact: skills/api-to-typemcp/SKILL.md

Read AGENTS.md before changing the bundled engine. Do not represent planned HTTP transport or public registry publication as implemented behavior before their separate reviewed releases.