{"_id":"@avinashchby/mcpcard","name":"@avinashchby/mcpcard","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@avinashchby/mcpcard","version":"0.1.0","description":"Generate MCP Server Cards per SEP-1649 — let clients discover your server without connecting.","license":"MIT","author":{"name":"Avinash Chaubey"},"homepage":"https://github.com/avinashchaubey/mcpcard#readme","repository":{"type":"git","url":"git+https://github.com/avinashchaubey/mcpcard.git"},"bugs":{"url":"https://github.com/avinashchaubey/mcpcard/issues"},"keywords":["mcp","model-context-protocol","server-card","sep-1649","cli","introspection","metadata"],"type":"module","bin":{"mcpcard":"bin/mcpcard.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./middleware":{"types":"./dist/serve/middleware.d.ts","import":"./dist/serve/middleware.js"}},"engines":{"node":">=18"},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.27.1","ajv":"^8.17.1","commander":"^12.1.0","express":"^4.21.0","glob":"^11.0.0","typescript":"^5.6.0"},"devDependencies":{"@types/express":"^5.0.0","@types/node":"^22.0.0","tsup":"^8.3.0","typescript":"^5.6.0","vitest":"^2.1.0"},"gitHead":"253e9a1d4ba04588890e5d9eb78ada7d65d1205a","_id":"@avinashchby/mcpcard@0.1.0","_nodeVersion":"25.5.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-zp8oW+zoZvBK7vzk7A3uvpomoIqKSiIn0Gegxr16DXVngy2BYas5K7j0jtl8uN4LPw1p4MB/3wGGqHH2vTfYhw==","shasum":"4f976c102ecc6397fd6c0d26d337f9fcd61ef121","tarball":"https://registry.npmjs.org/@avinashchby/mcpcard/-/mcpcard-0.1.0.tgz","fileCount":18,"unpackedSize":49228,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBHuBNPTyJ3XmRTBhRIyQ1wBS4Hi7icjt0+P+5aV/HdcAiBuiy2SFVsnnK8fKyOHaIYtmveMXIiX9buIx3fZ4b0uhw=="}]},"_npmUser":{"name":"avinashchby","email":"avinashchby@gmail.com"},"directories":{},"maintainers":[{"name":"avinashchby","email":"avinashchby@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcpcard_0.1.0_1773907009643_0.6721300353553952"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T07:56:49.526Z","0.1.0":"2026-03-19T07:56:49.788Z","modified":"2026-03-19T07:56:50.083Z"},"maintainers":[{"name":"avinashchby","email":"avinashchby@gmail.com"}],"description":"Generate MCP Server Cards per SEP-1649 — let clients discover your server without connecting.","homepage":"https://github.com/avinashchaubey/mcpcard#readme","keywords":["mcp","model-context-protocol","server-card","sep-1649","cli","introspection","metadata"],"repository":{"type":"git","url":"git+https://github.com/avinashchaubey/mcpcard.git"},"author":{"name":"Avinash Chaubey"},"bugs":{"url":"https://github.com/avinashchaubey/mcpcard/issues"},"license":"MIT","readme":"# mcpcard\n\n**Make your MCP server discoverable without a single connection.**\n\n[![npm version](https://img.shields.io/npm/v/mcpcard)](https://www.npmjs.com/package/mcpcard)\n[![license](https://img.shields.io/npm/l/mcpcard)](./LICENSE)\n[![node](https://img.shields.io/node/v/mcpcard)](https://nodejs.org)\n\n`mcpcard` generates [MCP Server Cards](https://spec.modelcontextprotocol.io) per the **SEP-1649** specification. A server card is a static JSON file at `/.well-known/mcp/server-card.json` that describes your server's tools, resources, prompts, transport, and auth — so clients, registries, and crawlers can discover what you offer without ever connecting.\n\n## Quickstart\n\n```bash\nnpx mcpcard scan ./my-server\n# => .well-known/mcp/server-card.json\n```\n\nThat's it. One command, one file, full discoverability.\n\n## Why This Exists\n\nMCP servers are invisible until a client connects and runs the handshake. That means:\n\n- **Registries can't index you** without spawning your server\n- **Clients can't show your capabilities** before the user connects\n- **Crawlers have nothing to parse** — your tools/resources are locked behind a protocol\n\nServer Cards fix this. They're the `robots.txt` of MCP — a static, well-known file that says \"here's what I do\" without requiring a live connection.\n\n`mcpcard` generates that file from your source code, a running server, or validates one you wrote by hand.\n\n## Install\n\n```bash\nnpm install -g mcpcard    # global CLI\nnpm install mcpcard       # local dependency + Express middleware\n```\n\nOr just use `npx mcpcard` — no install needed.\n\n## CLI\n\n### `scan` — Generate a card from source code\n\n```bash\nnpx mcpcard scan ./my-server\nnpx mcpcard scan ./my-server -o ./card.json\nnpx mcpcard scan ./my-server --verbose\n```\n\nStatically analyzes your TypeScript or Python MCP server. Detects:\n\n| Pattern | Language |\n|---------|----------|\n| `server.tool()` / `server.resource()` / `server.prompt()` | TypeScript/JS |\n| `@mcp.tool()` / `@mcp.resource()` / `@mcp.prompt()` | Python |\n| `new StdioServerTransport()` / `new SSEServerTransport()` | TypeScript/JS |\n| `FastMCP(\"name\")` / `McpServer({ name, version })` | Both |\n\n### `live` — Introspect a running server\n\n```bash\n# stdio — spawns the process for you\nnpx mcpcard live --command \"node server.js\"\nnpx mcpcard live -c \"python server.py\"\n\n# HTTP — connects to a remote server\nnpx mcpcard live --url https://example.com/mcp\nnpx mcpcard live -u http://localhost:8080/mcp\n```\n\nConnects via MCP protocol, runs `initialize` + `tools/list` + `resources/list` + `prompts/list`, and writes the card. Use this when static analysis misses something, or when you don't have source access.\n\n### `validate` — Check a card against the schema\n\n```bash\nnpx mcpcard validate server-card.json\n# exit 0 = valid, exit 1 = errors printed\n```\n\n### `serve` — Host a card locally\n\n```bash\nnpx mcpcard serve server-card.json\nnpx mcpcard serve server-card.json --port 8080\n# => http://localhost:3000/.well-known/mcp/server-card.json\n```\n\n## Add a Server Card in 30 Seconds\n\n**Option A** — Generate from source:\n\n```bash\nnpx mcpcard scan ./my-server\n# Deploy .well-known/mcp/server-card.json with your server\n```\n\n**Option B** — Express middleware (zero files):\n\n```typescript\nimport express from 'express';\nimport { mcpCardMiddleware } from 'mcpcard/middleware';\n\nconst app = express();\napp.use(mcpCardMiddleware('./server-card.json'));\napp.listen(3000);\n// => GET /.well-known/mcp/server-card.json\n```\n\nYou can also pass a card object directly:\n\n```typescript\napp.use(mcpCardMiddleware({\n  name: 'my-server',\n  version: '1.0.0',\n  description: 'My MCP server',\n  capabilities: { tools: true },\n  protocol_version: '2025-11-05',\n  tools: [{ name: 'hello', description: 'Say hello' }]\n}));\n```\n\n**Option C** — Generate from a running server:\n\n```bash\nnpx mcpcard live -c \"node my-server.js\" -o .well-known/mcp/server-card.json\n```\n\n## Server Card Format (SEP-1649)\n\n```json\n{\n  \"name\": \"my-mcp-server\",\n  \"version\": \"1.0.0\",\n  \"description\": \"What this server does\",\n  \"homepage\": \"https://example.com\",\n  \"transport\": {\n    \"type\": \"streamable-http\",\n    \"url\": \"https://example.com/mcp\"\n  },\n  \"authentication\": {\n    \"type\": \"oauth2\",\n    \"authorization_url\": \"https://example.com/auth\",\n    \"token_url\": \"https://example.com/token\",\n    \"scopes\": [\"read\", \"write\"]\n  },\n  \"capabilities\": {\n    \"tools\": true,\n    \"resources\": true,\n    \"prompts\": true\n  },\n  \"tools\": [\n    {\n      \"name\": \"search_issues\",\n      \"description\": \"Search GitHub issues\",\n      \"inputSchema\": { \"type\": \"object\" },\n      \"annotations\": { \"readOnly\": true }\n    }\n  ],\n  \"resources\": [\n    {\n      \"uri\": \"repo://main/readme\",\n      \"name\": \"readme\",\n      \"description\": \"Repository README\"\n    }\n  ],\n  \"prompts\": [\n    {\n      \"name\": \"summarize\",\n      \"description\": \"Summarize an issue\"\n    }\n  ],\n  \"protocol_version\": \"2025-11-05\"\n}\n```\n\n## Programmatic API\n\n```typescript\nimport { buildCard, validateCard } from 'mcpcard';\nimport type { ServerCard, McpTool } from 'mcpcard';\n\nconst card = buildCard({\n  name: 'my-server',\n  description: 'Does things',\n  tools: [{ name: 'hello', description: 'Say hello' }]\n});\n\nconst result = validateCard(card);\n// { valid: true, errors: [] }\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-148a5d4144c6cefd55c5fed139a11d47"}