{"_id":"@agenttic-ai-dev/skill2mcp","name":"@agenttic-ai-dev/skill2mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agenttic-ai-dev/skill2mcp","version":"0.1.0","description":"CLI and library to parse SKILL.md files into MCP-ready tool definitions","keywords":["mcp","model-context-protocol","agents","cli","typescript"],"license":"MIT OR Apache-2.0","author":{"name":"Agenttic AI","email":"agenttic.ai@gmail.com"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"bin":{"skill2mcp":"dist/cli/index.js"},"engines":{"node":">=20.0.0"},"repository":{"type":"git","url":"git+https://github.com/agenttic-ai-dev/skill2mcp.git"},"bugs":{"url":"https://github.com/agenttic-ai-dev/skill2mcp/issues"},"homepage":"https://github.com/agenttic-ai-dev/skill2mcp#readme","publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","dev":"tsx src/cli/index.ts","parse":"tsx src/cli/index.ts parse","inspect":"tsx src/cli/index.ts inspect","gen":"tsx src/cli/index.ts build","pack:check":"npm pack --dry-run","prepublishOnly":"npm run build && npm test && npm run pack:check","test":"vitest run","test:watch":"vitest"},"dependencies":{"commander":"^14.0.1","gray-matter":"^4.0.3"},"devDependencies":{"@types/node":"^24.7.2","tsx":"^4.20.6","typescript":"^5.9.3","vitest":"^3.2.4"},"_id":"@agenttic-ai-dev/skill2mcp@0.1.0","gitHead":"b86b47967304af5d46d15eacff4dcbff45777814","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-kFVNZYrjIPdUjT2T12tK1LLL1jVtHREu+IrvpoyGNyWETOIha4uw5aK7u9yN32XbR0ExiWiNypz5oySVl6O6Iw==","shasum":"6bbc885b20d8d5d37e89c450d444a8ccc4d2566e","tarball":"https://registry.npmjs.org/@agenttic-ai-dev/skill2mcp/-/skill2mcp-0.1.0.tgz","fileCount":44,"unpackedSize":67542,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDddHhkOPSWgHOkUN7aKfZcMM0vr83z4yjoPxmMvdM85AiEA4MwnjkNxXJzT9/b+ctgrAXgTSr058p0tHWgQ4kMGTDQ="}]},"_npmUser":{"name":"agenttic-ai-dev","email":"dev@agenttic.ai"},"directories":{},"maintainers":[{"name":"agenttic-ai-dev","email":"dev@agenttic.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/skill2mcp_0.1.0_1777095224201_0.9034047813128498"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-25T05:33:44.118Z","0.1.0":"2026-04-25T05:33:44.340Z","modified":"2026-04-25T05:33:44.528Z"},"maintainers":[{"name":"agenttic-ai-dev","email":"dev@agenttic.ai"}],"description":"CLI and library to parse SKILL.md files into MCP-ready tool definitions","homepage":"https://github.com/agenttic-ai-dev/skill2mcp#readme","keywords":["mcp","model-context-protocol","agents","cli","typescript"],"repository":{"type":"git","url":"git+https://github.com/agenttic-ai-dev/skill2mcp.git"},"author":{"name":"Agenttic AI","email":"agenttic.ai@gmail.com"},"bugs":{"url":"https://github.com/agenttic-ai-dev/skill2mcp/issues"},"license":"MIT OR Apache-2.0","readme":"# skill2mcp\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE-MIT)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE-APACHE)\n[![Language](https://img.shields.io/github/languages/top/agenttic-ai-dev/skill2mcp)](https://github.com/agenttic-ai-dev/skill2mcp)\n\n![skill2mcp header](./res/65338260-5263-4789-ad59-9b2bbff4bc4e.png)\n\n`skill2mcp` is a TypeScript CLI/library that converts `SKILL.md` documents into MCP-ready tool definitions and can generate a minimal deployable MCP Server package from a single file or an entire skills directory.\n\nThe generated server uses the official MCP TypeScript SDK (`@modelcontextprotocol/sdk`) and supports `stdio`, `http`, or `both` transports.\n\n## Why this project\n\nSKILL documents are usually semi-structured markdown (frontmatter + prose + tables). MCP tools require strict contracts (`name`, `description`, `inputSchema`).\n\n`skill2mcp` bridges that gap with a layered pipeline:\n\n1. Parse markdown into a stable Intermediate Representation (IR)\n2. Transform IR into MCP tool definitions\n3. Generate a deployable MCP server package with handler stubs\n\n## Current status\n\nMVP implemented and working:\n\n- Deterministic parser (`strict`, `tolerant`)\n- Cascading semantic mode (`semantic`) for missing metadata fallback\n- Tool transformation (`SchemaBuilder`, `ToolMapper`, `ToolValidator`)\n- `inspect` output with MCP-style tool JSON\n- `build` output with deployable MCP server package\n- Generated server supports `stdio` + `http`\n- `build --watch` for iterative regeneration\n\n## Installation\n\n### Requirements\n\n- Node.js 20+\n- npm 10+\n\n### Local install\n\n```bash\nnpm install\n```\n\n### Install from npm\n\n```bash\nnpm install -g @agenttic-ai-dev/skill2mcp\n# or without global install\nnpx @agenttic-ai-dev/skill2mcp parse ./skills\n```\n\n### Build CLI\n\n```bash\nnpm run build\n```\n\n## Quick start\n\n### 1. Parse a single SKILL\n\n```bash\nnpm run parse -- ./fixtures/skills/valid-skill.md --mode strict\n```\n\n### 2. Inspect generated tool definitions\n\n```bash\nnpm run inspect -- ./fixtures/skills --mode tolerant\n```\n\n### 3. Generate deployable MCP server package\n\n```bash\nnpm run gen -- ./fixtures/skills --out ./generated/mcp-server --transport both --mode tolerant\n```\n\n### 4. Run generated server\n\n```bash\ncd ./generated/mcp-server\nnpm install\nnpm run build\nnpm run start:stdio\n# or\nnpm run start:http\n```\n\nHTTP endpoint:\n\n```text\nPOST /mcp\n```\n\n## CLI reference\n\n### `parse`\n\nConverts SKILL markdown to IR JSON.\n\n```bash\nskill2mcp parse <input> [--mode strict|tolerant|semantic]\n```\n\nArguments:\n\n- `<input>`: path to a `.md` file or directory\n\nOptions:\n\n- `--mode`: parser mode (`tolerant` default)\n- `--format`: currently `json`\n\nOutput:\n\n- `results[]` with parsed `SkillDocument`\n- `diagnostics[]` per source file\n\n### `inspect`\n\nConverts parsed IR into MCP-like tool definitions.\n\n```bash\nskill2mcp inspect <input> [--mode strict|tolerant|semantic]\n```\n\nOutput:\n\n- `tools[]`: generated tool definitions (`name`, `description`, `inputSchema`)\n- `results[]`: tool + diagnostics per source\n\n### `build`\n\nGenerates a deployable MCP server package from one or many skills.\n\n```bash\nskill2mcp build <input> --out <dir> [--transport stdio|http|both] [--mode strict|tolerant|semantic] [--watch]\n```\n\nArguments:\n\n- `<input>`: path to a `.md` file or directory\n\nRequired options:\n\n- `--out`: output directory for generated package\n\nOptional options:\n\n- `--transport`: default generated server transport (`both` default)\n- `--mode`: parsing mode (`tolerant` default)\n- `--watch`: regenerate package on source changes\n\nOutput:\n\n- generated package files (`package.json`, `tools.json`, `src/server.ts`, handlers)\n- diagnostics summary in JSON\n\n## Parse modes\n\n### `strict`\n\n- Fails on required metadata/schema gaps\n- Best for CI quality gates\n\n### `tolerant`\n\n- Continues with warnings for missing fields\n- Best for batch processing mixed-quality skills\n\n### `semantic`\n\n- Starts from tolerant parse\n- Attempts semantic extraction through OpenRouter (when configured)\n- Applies deterministic fallback inference for unresolved fields\n- Keeps diagnostics trace (`SEMANTIC_*` codes)\n\n### OpenRouter configuration for `semantic`\n\nEnvironment variables:\n\n- `OPENROUTER_API_KEY`: enables remote semantic extraction\n- `OPENROUTER_MODEL` (optional): defaults to `anthropic/claude-3.5-sonnet`\n- `SKILL2MCP_CACHE_DIR` (optional): override cache directory\n- `OPENROUTER_HTTP_REFERER` (optional): forwarded as OpenRouter header\n- `OPENROUTER_X_TITLE` (optional): forwarded as OpenRouter header\n\nCache behavior:\n\n- Semantic responses are cached by content hash in `.skill2mcp-cache/semantic-openrouter-cache.json`\n- If cache is present, semantic mode reuses cache and avoids extra remote calls\n\n## Canonical `SKILL.md` format (recommended)\n\n```md\n---\nname: docx-generator\nversion: 1.0.0\ndescription: Generate Word docs from structured markdown\ntags: [documents, office]\n---\n\n## Parameters\n| Name | Type | Required | Default | Description |\n|------|------|----------|---------|-------------|\n| content | string | yes |  | Markdown content |\n| title | string | yes |  | Document title |\n\n## Examples\n**Input:** `{ content: \"# Hello\", title: \"Report\" }`\n**Output:** report.docx generated at /outputs/\n\n## Triggers\n- \"generate document\"\n- \"create report\"\n```\n\n## Generated package structure\n\n```text\ngenerated/mcp-server/\n  package.json\n  tsconfig.json\n  README.md\n  tools.json\n  src/\n    server.ts\n    generated-tools.ts\n    handlers/\n      index.ts\n      <tool_name>.ts\n```\n\n## Development\n\n### Scripts\n\n```bash\nnpm run build       # compile TypeScript\nnpm run test        # run test suite\nnpm run parse       # parse command entry\nnpm run inspect     # inspect command entry\nnpm run gen         # build command entry\nnpm run pack:check  # verify npm package contents\n```\n\n### Publish to npm\n\n```bash\n# Login with publishing account (agenttic.ai@gmail.com)\nnpm adduser\n\n# Final verification\nnpm run prepublishOnly\n\n# Publish public package\nnpm publish --access public\n```\n\n### Test suite\n\nCurrent automated coverage includes:\n\n- parser behavior (`strict`, `tolerant`, `semantic`)\n- schema builder and tool mapping\n- inspect command output contract\n- end-to-end build artifact generation\n\n## Engineering conventions\n\n- Follow repository collaboration rules in `AGENTS.md`\n- Product/business directives are governed by `ROADMAP.md`\n- Commit messages must use `[AI]` prefix when AI-generated\n\n## Release artifacts\n\nThis repo includes:\n\n- Dual-license distribution: `MIT OR Apache-2.0`\n- `CHANGELOG.md`\n- `CONTRIBUTING.md`\n- `RELEASE_CHECKLIST.md`\n\n## Collaboration model\n\n- Governance and decision rules: `GOVERNANCE.md`\n- Code of conduct: `CODE_OF_CONDUCT.md`\n- Security reporting: `SECURITY.md`\n- Support channels: `SUPPORT.md`\n\n## Known limitations\n\n- Parameter parsing currently assumes markdown table format in `## Parameters`\n- Semantic mode prioritizes missing metadata and may enrich missing parameters when extraction is available\n- Watch mode tracks current tree; if deeply nested folders are added later, restart watch for complete coverage\n\n## Roadmap alignment\n\nThe active implementation follows phased delivery in `ROADMAP.md`.\n\nGenAI integration policy (when enabled) prioritizes OpenRouter as default provider strategy, as defined in roadmap directives.\n\n## License\n\nLicensed under either of:\n\n- MIT License (`LICENSE-MIT`)\n- Apache License 2.0 (`LICENSE-APACHE`)\n\nat your option.\n","readmeFilename":"README.md","_rev":"1-760adc6b4ca444908390bc06a3cdc1ca"}