{"_id":"@agentmeasure/mcp","_rev":"3-177222b276c6848098e2d32f1d33af1b","name":"@agentmeasure/mcp","dist-tags":{"latest":"0.2.0"},"versions":{"0.0.0-stage":{"name":"@agentmeasure/mcp","version":"0.0.0-stage","_id":"@agentmeasure/mcp@0.0.0-stage","stub":true,"maintainers":[{"name":"tongroy","email":"tongroy18@gmail.com"}],"dist":{"shasum":"a919d19161d267f25a1eb43961d2d03ad5ff8e0f","tarball":"https://registry.npmjs.org/@agentmeasure/mcp/-/mcp-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-gVs3ESHccRVyNc2kiJG77NXnIkbktHOnhAv2TJgseFIJAO2d+jr1ZDsAo1AB2GTr6zrTSAnNDTClyRGvA3pKkg==","signatures":[{"sig":"MEUCICQ10iMqvwmgJyiqpO8pwaop9LndnZLRTnPaq5Le+RHdAiEAw3JkXN1OEcLFcHiqy5/OuZLYce2b7fDnhRwrBsRYgYM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":339},"_npmUser":{"name":"tongroy","email":"tongroy18@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.1.1":{"name":"@agentmeasure/mcp","version":"0.1.1","keywords":["agent","mcp","measurement","analytics","agentmeasure","observability"],"license":"MIT","_id":"@agentmeasure/mcp@0.1.1","maintainers":[{"name":"tongroy","email":"tongroy18@gmail.com"}],"dist":{"shasum":"d7662acef33708c9fc0d5b891d5c5d930edac76f","tarball":"https://registry.npmjs.org/@agentmeasure/mcp/-/mcp-0.1.1.tgz","fileCount":5,"integrity":"sha512-Ocif062JmMeBfoJm5Ha/+3Zau2H3g7WT6yeFwwcYjwoecJCxE9edByTaZ+qM1nMQCaW5nQMagm7I+Z9NHabbng==","signatures":[{"sig":"MEUCIQCWjzMvRYwkczECQzV/jpYpjj0nc+xjtS3VHRJHIdgwxQIgeJ6L6OL7YxDXKePHgrqZ2kDmLqBV/C2HL9Gk4Q6mcI4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIEuWTBqppLJjxKc+JULHvQgrdUsHaSxbKZx2FKorwZ/GAiAIYaBM/ZgHUiErzdrO1twGSmQH0M45IKzyFjj4mo5Shg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30868},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"631c2bfdbe51681a0bb48ac8037eac25504f2cef","scripts":{"test":"node --test \"test/*.test.mjs\"","build":"tsc -p tsconfig.json","example":"node examples/mcp-integration.js"},"_npmUser":{"name":"tongroy","email":"tongroy18@gmail.com"},"_npmVersion":"10.9.9","description":"AgentMeasure Provider SDK — observe-first capability usage measurement for MCP servers. Emits canonical observations (AgentMeasure Draft 0.4.3); non-blocking buffered spool; no content captured.","directories":{},"_nodeVersion":"22.23.3","_hasShrinkwrap":false,"devDependencies":{"zod":"^4.0.0","typescript":"^5.5.0","@types/node":"^26.2.0","@modelcontextprotocol/sdk":"^1.30.0","@modelcontextprotocol/client":"^2.0.0","@modelcontextprotocol/server":"^2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.1_1791676578013_0.8289607156589607","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"@agentmeasure/mcp@0.2.0","dist":{"shasum":"d0c8a1561ff787b4de057af471af92060809111a","tarball":"https://registry.npmjs.org/@agentmeasure/mcp/-/mcp-0.2.0.tgz","fileCount":5,"integrity":"sha512-WkmbSWodSN7yI7v8uBT9YT5Ou8zspg4J1w2ayZq96uiMHJAdRbu1OICyqpZm3Rw7aQvyvLdj0iff/CQSY/T1Hw==","signatures":[{"sig":"MEUCIDonCWyNJmsE7CvaX+UICJA+A/B+RetRq18gLPkpbfbaAiEA2sve8f6TSI1vFB9f4SNBqoLzGnFRwZo67Wc6/OsSrow=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGiwKD6p3oMJ3O+6rbWq214F/EWvYnF1b7Mo9i5DNQHDAiAd3HZVlZZ9mPFCjN/Oqb2O83MCBoFKXQ3VExywRV/1Yg=="}],"unpackedSize":31908},"main":"dist/index.js","name":"@agentmeasure/mcp","type":"module","types":"dist/index.d.ts","gitHead":"23ed0803f28d0aa7066dcbed71c2100268856a45","license":"MIT","scripts":{"test":"node --test \"test/*.test.mjs\"","build":"tsc -p tsconfig.json","example":"node examples/mcp-integration.js"},"version":"0.2.0","_npmUser":{"name":"tongroy","email":"tongroy18@gmail.com"},"keywords":["agent","mcp","measurement","analytics","agentmeasure","observability"],"_npmVersion":"10.9.9","description":"AgentMeasure Provider SDK — observe-first capability usage measurement for MCP servers. Emits canonical observations (AgentMeasure Draft 0.4.3); non-blocking buffered spool; no content captured.","directories":{},"maintainers":[{"name":"tongroy","email":"tongroy18@gmail.com"}],"_nodeVersion":"22.23.3","_hasShrinkwrap":false,"devDependencies":{"zod":"^4.0.0","typescript":"^5.5.0","@types/node":"^26.2.0","@modelcontextprotocol/sdk":"^1.30.0","@modelcontextprotocol/client":"^2.0.0","@modelcontextprotocol/server":"^2.0.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.2.0_1791942585556_0.13197478253556683"}}},"time":{"created":"2026-10-10T23:54:41.234Z","modified":"2026-10-14T01:49:45.845Z","0.0.0-stage":"2026-10-10T23:54:41.234Z","0.1.1":"2026-10-10T23:56:18.097Z","0.2.0":"2026-10-14T01:49:45.634Z"},"license":"MIT","keywords":["agent","mcp","measurement","analytics","agentmeasure","observability"],"description":"AgentMeasure Provider SDK — observe-first capability usage measurement for MCP servers. Emits canonical observations (AgentMeasure Draft 0.4.3); non-blocking buffered spool; no content captured.","maintainers":[{"name":"tongroy","email":"tongroy18@gmail.com"}],"readme":"# @agentmeasure/mcp\n\n**AgentMeasure Provider SDK** — observe-first capability usage measurement for MCP\nservers. Emits Canonical Observations (AgentMeasure Draft 0.4.3); non-blocking\nbuffered spool; no content captured.\n\n```bash\n# npm registry publish pending — install from the release tarball:\nnpm install https://github.com/roy-tong/AgentMeasure/releases/download/v0.1.1/agentmeasure-mcp-0.1.1.tgz\n```\n\n## MCP SDK v2 (primary) — `@modelcontextprotocol/server`\n\n```ts\nimport { McpServer } from \"@modelcontextprotocol/server\";\nimport { agentmeasure } from \"@agentmeasure/mcp\";\n\nconst mw = agentmeasure({ projectId: \"github.com/acme/weather-service\" });\n\nconst server = new McpServer({ name: \"acme-weather\", version: \"1.0.0\" });\nserver.registerTool(\n  \"get_weather\",\n  { inputSchema: z.object({ city: z.string() }) },\n  mw.wrapTool(\"get_weather\", handler, {\n    // per-request caller: v2 clients attach clientInfo to every request\n    getCaller: (ctx) => claimFrom(ctx.mcpReq?._meta?.clientInfo),\n  }),\n);\n```\n\n## MCP SDK v1 (compatibility) — `@modelcontextprotocol/sdk`\n\n```ts\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { agentmeasure } from \"@agentmeasure/mcp\";\n\nconst mw = agentmeasure({ projectId: \"github.com/acme/weather-service\" });\nconst server = new McpServer({ name: \"acme-weather\", version: \"1.0.0\" });\nconst origTool = server.tool.bind(server);\nserver.tool = (name, schema, handler) =>\n  origTool(name, schema, mw.wrapTool(name, handler, {\n    getCaller: (ctx) => sessions.get(ctx?._meta?.sessionId ?? \"\"),\n  }));\n```\n\nFull runnable examples (v1 + v2): `sdk/examples/mcp-integration.js` and\n`mcp-integration-v2.js` — each emits **42 calls → 84 canonical observations**\n(attempt_started + attempt_completed only).\n\n## Declaring tool annotations (do as we say, and as we do)\n\nAgents and registries reason about your tools from their annotations before\never calling them. Declare them on every tool — we do, in our own examples:\n\n```js\nserver.registerTool(\"get_weather\", {\n  inputSchema: z.object({ city: z.string() }),\n  annotations: {\n    readOnlyHint: true,       // no state changes\n    destructiveHint: false,   // explicit even when it is the default\n    idempotentHint: true,     // Optional in the spec — set it when true\n    openWorldHint: true,      // reaches outside the server\n  },\n}, handler);\n```\n\n`readOnlyHint`, `destructiveHint` and `openWorldHint` should always be\ndeclared; `idempotentHint` is Optional in the current spec. A tool that\nwrites should say so (`readOnlyHint: false, destructiveHint: true`) — a\nwrong annotation is worse than none, and registries increasingly check.\n\n## What you get (local, no cloud)\n\n```bash\npython3 product/local-analytics.py ~/.agentmeasure/events/agentmeasure-events.jsonl --project github.com/acme/weather-service\n```\n\n```text\nCanonical observations accepted : 84   rejected: 0\nObserved attempts               : 42\nStrict Qualified attempts      : 0 (0.0%)          # synthetic → never production\nSuccess / Failure              : success-rate 90.5%\nLatency (duration_ms)          : n=42 mean=168ms p50=165ms p95=297ms\nOperation resolution           : resolved 0 / 42 attempts (coverage 0.0%)   # fail-closed\nCaller attribution             : claude:14 codex:14 unknown:14 (declared=28 / unknown=14)\n```\n\n## Core promises\n\n| Promise | Implementation |\n| --- | --- |\n| Observe first, qualify later | `usage_context` / `validity` default `unknown`; fixtures label themselves (`synthetic`) |\n| Validity discipline | providers can only claim validity they can know (`health_check` / `load_test` / `suspected_invalid` / `duplicate`); `normal` is collector-derived and never claimable from config |\n| Fail-open | `emit()` never throws into your handler; business errors propagate normally |\n| Not on critical path | `emit()` only enqueues; background flusher batches writes (no sync IO in the request path) |\n| Durable best-effort buffering | memory queue → batch flush → rotating spool files (default 5 MiB / keep 7); spool dir 0700, files 0600 |\n| Loss accounting | `bufferHealth`: queueDepth · droppedTotal · droppedSinceLastFlush · flushFailures · spoolBytes · rotatedFiles |\n| Crash boundary | up to one flush interval of in-memory observations may be lost on abrupt termination (SIGKILL/crash); `await am.shutdown()` drains; optional `handleSignals` hooks SIGTERM/SIGINT |\n| No content | arguments/results/paths unreachable by design |\n| Caller per-request | `getCaller(ctx)` resolves per request (v2 `_meta.clientInfo` / v1 `_meta.sessionId` echo); server-level claim is a fallback for fixtures only |\n| Canonical output | validated against `schemas/observation.schema.json` (vocab driven by `registry/vocabularies.yaml`); lineage snake_case (`operation_id` / `task_id` / `retry_of`) |\n| MCP-version-agnostic | the SDK imports no MCP package; v1/v2 adapters live in the examples (no peer dependency) |\n\n## Buffer model\n\n```text\nRequest\n  │\n  ├── enqueue Observation (emit() — no IO)\n  ▼\nReturn\n\nBackground flusher\n  ↓\nmemory queue → batch → rotating spool files\n```\n\n`bufferHealth` exposes the loss accounting the standard requires; the same numbers\nare stamped into each persisted batch's `collection_health` block.\n\n**Multi-process deployments**: `eventsDir` MUST NOT be shared between processes\nin 0.1.x. Give each process its own file, e.g.\n`agentmeasure({ spoolFileName: \\`agentmeasure-events-${process.pid}.jsonl\\` })`,\nand point the collector at the `agentmeasure-events-*.jsonl` glob.\n\n**Deterministic fixtures**: `wrapTool(..., { durationMs })` accepts a fixed value\nor a function sampled at completion time — used by the demo fixture so that\nsame fixture + same policy = bitwise-identical semantic output. Production\ndeployments omit it; the middleware then records measured wall time.\n\n## Development\n\n```bash\nnpm install && npm run build\nnpm test                       # schema / fail-open / privacy / lineage / caller /\n                               # concurrency / buffer / mcp-integration (v1+v2)\nnode examples/mcp-integration.js      # v1 path → local JSONL\nnode examples/mcp-integration-v2.js   # v2 path (primary) → local JSONL\n```\n\n## Status\n\nv0.2.0 — annotations guidance in examples + README (the metering standard's\nown SDK declares what it preaches). Event schema unchanged from 0.1.x.\n\nv0.1.1 — External-Ready. Standard (Draft 0.4.3), reference collector, conformance\nsuite and canonical pipeline gates are stable; hosted ingestion and dashboard are\nnext (product/MVP.md). MIT licensed.\n","readmeFilename":"README.md"}