{"_id":"@vayacore/mcp","_rev":"2-55289ee7c972c54fb4e74c2ba69846ff","name":"@vayacore/mcp","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.1":{"name":"@vayacore/mcp","version":"0.1.1","keywords":["mcp","model-context-protocol","vayapin","geocoding","shipping"],"license":"UNLICENSED","_id":"@vayacore/mcp@0.1.1","maintainers":[{"name":"martinshein","email":"martin@di-atomic.com"}],"homepage":"https://github.com/martinshein/vayacore#readme","bugs":{"url":"https://github.com/martinshein/vayacore/issues"},"bin":{"vayapin-mcp":"dist/server.js"},"dist":{"shasum":"f30f96b23a0aa6f2c17699d93661118b005c0829","tarball":"https://registry.npmjs.org/@vayacore/mcp/-/mcp-0.1.1.tgz","fileCount":50,"integrity":"sha512-qPEDhGbF/dzd28KEpYrZT0FYtceKtudzlIDp2ZjQZw0IVuYynoevxoxxVuXcoEmijpVsj3KZjD1AWj/n/GIigQ==","signatures":[{"sig":"MEUCIG+Qjz4AxywFeKBAEFfNkMk4El5uGdB0veLqbiSXilfNAiEAnXiiyo4hQpQNZGZTw7Jfz/DZuke4Eh14/ehwN5KMcq4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":116811},"main":"dist/server.js","type":"module","types":"./dist/server.d.ts","engines":{"node":">=20"},"exports":{".":"./dist/server.js"},"mcpName":"app.vayapin/mcp","_npmUser":{"name":"martinshein","email":"martin@di-atomic.com"},"repository":{"url":"git+https://github.com/martinshein/vayacore.git","type":"git","directory":"apps/mcp"},"_npmVersion":"10.8.2","description":"Model Context Protocol server for VayaPin — VayaPin pin resolution, Google Maps, and AfterShip tools over a single MCP namespace, future-proofed against the 128-tool client ceiling.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"undici":"^6.21.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.1_1781916988210_0.18509826762157733","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@vayacore/mcp","version":"0.1.2","mcpName":"app.vayapin/mcp","description":"Model Context Protocol server for VayaPin — VayaPin pin resolution, Google Maps, and AfterShip tools over a single MCP namespace, future-proofed against the 128-tool client ceiling.","type":"module","repository":{"type":"git","url":"git+https://github.com/martinshein/vayacore.git","directory":"apps/mcp"},"main":"dist/server.js","bin":{"vayapin-mcp":"dist/server.js"},"exports":{".":"./dist/server.js"},"engines":{"node":">=20"},"keywords":["mcp","model-context-protocol","vayapin","geocoding","shipping"],"license":"UNLICENSED","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","undici":"^6.21.0"},"_id":"@vayacore/mcp@0.1.2","types":"./dist/server.d.ts","bugs":{"url":"https://github.com/martinshein/vayacore/issues"},"homepage":"https://github.com/martinshein/vayacore#readme","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-7zEHGdP8hTXVSrVKfTKc5b7lMVawX5UfmdZVARULC0bYWf4S7YPIkvi7sKpEdQM0SGVNxukUgn6a1H3BJU4e7w==","shasum":"24764394bb6af470101644ac73e03944d1e05f95","tarball":"https://registry.npmjs.org/@vayacore/mcp/-/mcp-0.1.2.tgz","fileCount":50,"unpackedSize":117510,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDG3fS//wPMEE6zqnlCfmvQ6e06XOs43+M0xm1CMCse5QIgWR9xPxNESoAWlycF7Zw+onuW0ai1LmMDUlkVpY9rQqc="}]},"_npmUser":{"name":"martinshein","email":"martin@di-atomic.com"},"directories":{},"maintainers":[{"name":"martinshein","email":"martin@di-atomic.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.1.2_1781918617647_0.20086952079998066"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-20T00:56:28.002Z","modified":"2026-06-20T01:23:37.929Z","0.1.1":"2026-06-20T00:56:28.372Z","0.1.2":"2026-06-20T01:23:37.799Z"},"bugs":{"url":"https://github.com/martinshein/vayacore/issues"},"license":"UNLICENSED","homepage":"https://github.com/martinshein/vayacore#readme","keywords":["mcp","model-context-protocol","vayapin","geocoding","shipping"],"repository":{"type":"git","url":"git+https://github.com/martinshein/vayacore.git","directory":"apps/mcp"},"description":"Model Context Protocol server for VayaPin — VayaPin pin resolution, Google Maps, and AfterShip tools over a single MCP namespace, future-proofed against the 128-tool client ceiling.","maintainers":[{"name":"martinshein","email":"martin@di-atomic.com"}],"readme":"# @vayapin/mcp\n\nModel Context Protocol server for VayaPin. Gives any MCP-compatible agent (Claude\nDesktop, Cursor, n8n, Zapier, …) VayaPin pin resolution plus Google Maps and\nAfterShip tools through a single tool namespace, authenticated with a Personal\nAccess Token.\n\n> **Status:** v0.1.2 — published to the VayaPin Verdaccio registry\n> (`@vayapin/mcp` on `https://npm.vayapin.app`), to public npmjs.com\n> (`@vayacore/mcp`), and listed in the official MCP Registry as `app.vayapin/mcp`.\n> Ships **8 P1 tools** over one MCP namespace:\n> `resolve_pin`, `preview_pin`, `confirm_pin` (VayaPin), `geocode`,\n> `reverse_geocode`, `place_search`, `place_details` (Google Maps via BYOK\n> proxy), and `track_package` (AfterShip via BYOK proxy), plus a `system_health`\n> sanity tool.\n\n## Install\n\n`@vayapin/mcp` lives on the VayaPin registry (`https://npm.vayapin.app`) and is\n**public — no registry token needed**. Map *only* the `@vayapin` scope to that\nregistry (its dependencies resolve from the public npm registry as usual). Add one\nline to your `.npmrc`:\n\n```ini\n# .npmrc\n@vayapin:registry=https://npm.vayapin.app\n```\n\nThen install or run it like any package:\n\n```bash\nnpm install @vayapin/mcp        # into a project\nnpx -y @vayapin/mcp             # no install\n```\n\n> **Don't** point your *default* registry at `npm.vayapin.app`\n> (`npm install --registry https://npm.vayapin.app …`). That routes this package's\n> dependencies through the private registry too, which requires auth — only the\n> `@vayapin` scope is public. The scoped `.npmrc` line above is the supported path.\n> (A `VAYAPIN_PAT` is still required at *runtime* to call the API — see below.)\n\n## Public distribution — `@vayacore/mcp` on npmjs.com\n\nThe package is **also published to the public npm registry as\n[`@vayacore/mcp`](https://www.npmjs.com/package/@vayacore/mcp)** — no `.npmrc`\nscope line required. This is the canonical install for outside developers and the\nartifact referenced by the official MCP registry.\n\n```bash\nnpx -y @vayacore/mcp             # no install, no .npmrc\nnpm install @vayacore/mcp        # into a project\n```\n\n> **Why two names?** The `@vayapin` npm **org** was unavailable on npmjs.com, so\n> the public scope is `@vayacore` (we own that org). The Verdaccio build keeps the\n> internal `@vayapin/mcp` name. Both ship the identical build; pick whichever\n> registry you already use. The two are kept in lockstep by\n> [`scripts/publish-npmjs.sh`](scripts/publish-npmjs.sh).\n\n**Registry status:** listed in the official\n[MCP Registry](https://registry.modelcontextprotocol.io) as **`app.vayapin/mcp`**\n(domain-verified via `vayapin.app`). Submission flow + reproduction:\n[`registry-submission.md`](registry-submission.md).\n\n## Configure (MCP client config)\n\nAdd the `@vayapin` scope line to your `~/.npmrc` (above) so `npx` can resolve the\npackage, then:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"vayapin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vayapin/mcp\"],\n      \"env\": {\n        \"VAYAPIN_PAT\": \"vayapin_pat_...\"\n        // optional: \"VAYAPIN_MCP_SLICE\": \"<slice-name>\"\n        // optional: \"VAYAPIN_MCP_API_URL\": \"https://api.vayapin.app/api/v1\"\n      }\n    }\n  }\n}\n```\n\nGenerate a PAT on the VayaPin developer portal (`POST /api/v1/auth/pat/request`).\nA 401 at runtime means the token is missing/expired/revoked — regenerate it.\n\n## Environment variables\n\n| Var | Required | Default | Purpose |\n|---|---|---|---|\n| `VAYAPIN_PAT` | yes | — | Personal Access Token, sent as `Authorization: Bearer`. |\n| `VAYAPIN_MCP_SLICE` | no | — | Name of a tool slice to expose (see ceiling lift). Unset → all tools. |\n| `VAYAPIN_MCP_API_URL` | no | `https://api.vayapin.app/api/v1` | Override for staging / self-host. |\n\n## The 128-tool ceiling lift — how it works, and why this shape\n\nMany MCP clients inject the **entire** tool list into the model's system prompt on\nevery turn. Past roughly **128 tools** some clients (Claude Desktop, Cursor,\nAntigravity, certain OpenAI Responses deployments) silently drop the tool\ninjection or burn a large slice of the context budget. A server that naively\nregisters its whole catalog breaks for those clients as it grows.\n\nThis server is built so it never hits that wall, using a well-established pattern\nfor large MCP catalogs. Two halves:\n\n1. **Named tool-slice allowlist, selected by an env var** *(implemented here).*\n   The full catalog is assembled internally, but an env var\n   (**`VAYAPIN_MCP_SLICE`**) names a frozen allowlist of tool names, and the\n   server exposes only that slice. This keeps the advertised tool count under any\n   client's ceiling even as the catalog grows.\n2. **Atomic per-product packages** *(deferred; not needed at 8 tools).* A future\n   option is to publish thin per-product wrapper packages — each registering only\n   its product's slice, with tool implementations shared from one core package. We\n   keep tools as data objects in group modules (`src/tools/*.ts`) so this split is\n   available later without rework.\n\n### Mechanism (this package)\n\n- The server uses the **low-level `Server` API** with manual `ListTools` /\n  `CallTool` handlers — **not** the high-level `server.tool()` helper. This is\n  what lets us control exactly which tools are advertised.\n- Tools are plain data: `{ name, description, inputSchema, execute }`\n  (`src/tools/types.ts`). The MCP layer never sees `execute`.\n- Tool groups register into a catalog via `register()` / `registerAll()`\n  (`src/tools/registry.ts`), wired from the append-only aggregation point\n  `src/tools/index.ts`.\n- At boot, `applySlice(catalog, VAYAPIN_MCP_SLICE)` filters the catalog. **Both**\n  `ListTools` and `CallTool` operate on the filtered set, so a hidden tool is\n  neither listed **nor** callable (calling one returns `MethodNotFound`).\n- No slice set → full catalog. Unknown slice name → full catalog + a stderr\n  warning (fail-open).\n\n> **Note — no \"meta-tool\".** We deliberately avoid a single runtime `list_tools`\n> meta-tool in favour of static named slices, which are simpler and fixed for the\n> process lifetime. The ceiling-lift proof lives in `tests/registry.test.ts`\n> (\"ceiling lift\" describe block): 200 stub tools + a 100-tool slice ⇒ exactly\n> 100 exposed.\n\n## Adding a tool (for tasks 4.2 / 4.3 / 4.4)\n\n1. Create `src/tools/<group>.ts` exporting `<group>Tools(client): ToolDefinition[]`.\n   Copy `src/tools/system.ts` as the template.\n2. Add **one** import + **one** `registerAll(<group>Tools(client))` line to\n   `src/tools/index.ts` (append-only — the Orchestrator union-merges this file).\n3. Add a test under `tests/`.\n\nUse snake_case tool names per VayaPin Product Definition v10 §6.1. Keep\ndescriptions one line — they cost context on every client turn.\n\n## Layout\n\n```\nsrc/\n  server.ts          entrypoint — boots Server over stdio, wires the registry\n  auth.ts            PAT loading + Bearer header (no token logging, no auto-refresh)\n  api/client.ts      undici HTTP client for api.vayapin.app/api/v1 (structured errors)\n  tools/\n    types.ts         ToolDefinition + JSON-Schema types (spec §6.1)\n    registry.ts      catalog + named-slice ceiling lift + ListTools/CallTool wiring\n    index.ts         append-only tool aggregation point\n    system.ts        system_health tool (canonical example group)\ntests/               vitest: registry (ceiling), auth, api client, server boot\n```\n\n## Develop\n\n```bash\nnpm ci\nnpm run build           # tsc → dist/\nnpm test                # vitest\nnpm test -- registry    # just the ceiling-lift proof\n```\n","readmeFilename":"README.md"}