Skip to main content
← Back to blog

Offline MCP Contract Tests (--self-test) for Directory Reviewers

Cowpin

Cowpin

10/18/2026

#mcp #testing #open-source #typescript #agents #cursor
Offline MCP Contract Tests (--self-test) for Directory Reviewers

MCP directories reject servers that look like closed hosted APIs with nothing inspectable in the repo. Fair — reviewers cannot run your production gateway without keys, billing, and trust.

Cowpin’s split is intentional:

  • Open-source stdio bridge (packages/mcp-server) — forwards JSON-RPC lines to HTTPS.
  • Hosted gateway (/api/agent/mcp) — tools, quotas, and cw_agent_… auth.

Reviewers should be able to verify the bridge offline. Users with keys verify tools live.

One command

From npm (once published):

npx -y @cowpin/mcp-server --self-test

From the monorepo:

pnpm --filter @cowpin/mcp-server test

Both run the same Node test runner suite — no COWPIN_AGENT_API_KEY, no outbound calls to cowpin.com (tests spin a local HTTP stub).

What the contract tests assert

  1. Forward — tools/list JSON-RPC POST reaches the configured gateway URL and the response line is relayed on stdout.
  2. Auth headers — Authorization: Bearer and X-Agent-Key when env is set; sensible fallbacks when not.
  3. Parse errors — garbage stdin yields JSON-RPC -32700, process keeps running.
  4. Unreachable gateway — -32603 with the request id preserved.
  5. Gateway errors — auth failures pass through untouched for the MCP client to show.

Implementation: packages/mcp-server/test/contract.test.mjs.

Why not test tools in --self-test?

Tool execution (cowpin_search_memory, saves, etc.) requires a real agent key and hits production data. That belongs in:

  • Deploy gate (test:guards includes the contract file).
  • Optional live smoke with COWPIN_AGENT_API_KEY (Connect Cursor).

Directory honesty: the bridge is fully auditable; the vault is a hosted service — same pattern as many official MCP servers that wrap SaaS APIs.

Mirror repo + npm

Canonical public source: github.com/cowpin-ai/mcp-server.

Before punkpeye/Glama resubmit:

MCP_MIRROR_DIR=~/clone/of/cowpin-ai/mcp-server pnpm sync:mcp-mirror

See docs/mcp-directory-verification.md for the checklist (npm token still operator-owned).

If you maintain an MCP server

Ship --self-test (or npm test with zero secrets) that:

  • Mocks the upstream HTTP/WebSocket boundary you control in OSS.
  • Documents what requires live credentials separately.

Reviewers and CI thank you; fewer “closed service” rejections.

Use Cowpin from an agent

After publish: add MCP via connect-cursor docs. Until npm is live, use the documented install script — not a mystery binary.