mcp-surface-lint

Static, design-level linting for MCP tool surfaces. Deterministic, offline, and it never calls an LLM.

This is a monorepo:

Quick start

npm install
npm run build          # builds core (the web app imports it)

npm test               # every package
npm run dev            # the web app on http://localhost:3000

The web app runs with no cloud accounts configured: reports are held in memory, rate limiting is off, and no analytics are sent. Copy apps/web/.env.example to .env.local to wire up the real services. See DEPLOYMENT.md for the production account, migration, publishing, and smoke-test checklist.

Releases

Production releases are semver Git tags (bare X.Y.Z, no v prefix — see .npmrc). From a clean main branch:

npm version patch
# or: npm version minor
# or: npm version major

That bumps the root version, runs preversion (npm run typecheck), then the version lifecycle syncs mcp-surface-lint and @mcplint/web to the same semver, stages workspace package.json files and package-lock.json, commits, and tags. postversion pushes the branch and tags to origin.

Advanced: bump one workspace only

When only the web app or CLI changed, you may want a partial bump. The default version hook syncs all workspaces to the root version, so partial bumps need --ignore-scripts and manual staging:

npm version patch -w @mcplint/web --include-workspace-root --ignore-scripts
# or: npm version patch -w mcp-surface-lint --include-workspace-root --ignore-scripts
git add package.json apps/*/package.json packages/*/package.json package-lock.json
git commit -m "$(node -p \"require('./package.json').version\")"
git tag "$(node -p \"require('./package.json').version\")"
git push origin HEAD --follow-tags

The release tag still follows the root version; deploy always runs, and npm/Registry publication is skipped when packages/core was not bumped.

npm version has no --dry-run; inspect npm help version or run on a throwaway clone before cutting a real release.

Full runbook: DEPLOYMENT.md.

The CLI

npm run mcplint -- --stdio "node dist/server.js"
npm run mcplint -- https://example.com/mcp
npm run mcplint -- snapshot.json

See packages/core/README.md for the full CLI, config, and scoring model, and packages/core/docs/rules.md for the rule catalogue.

Hosted MCP server

The web app also serves a stateless Streamable HTTP MCP endpoint at /api/mcp. It exposes one read-only tool, check_mcp_server, which accepts either a public HTTPS MCP URL (plus optional headers) or an inline tools/list snapshot. The result includes structured composite/category scores, footprint stats, and findings.

Each protocol request gets a fresh MCP server and transport. Tool inputs and captured schemas are not written to the report store. See /install in the running web app for current Cursor, VS Code, Claude, Windsurf, and generic client configurations.

What the web app does and does not do

• Ingest is paste-a-dump or connect-to-an-https-URL. It never spawns a process, so stdio servers are a job for the CLI.
• Remote capture is SSRF-guarded (apps/web/lib/ssrf.ts): https only, every resolved address must be public unicast, the socket is pinned to the vetted IP so DNS rebinding cannot move it, and redirects are re-validated at every hop.
• Reports are unlisted by default — an unguessable URL, noindex, deleted after 30 days unless the owner opts them public. Anyone with an unlisted URL can view it.
• The MCP endpoint is stateless — unlike the interactive report workflow, it returns a report directly and does not persist the input, captured schemas, or result.
• Everything is free. The GATE_FINDINGS flag and projectReport() exist so a paid tier could withhold the audit while leaving the score free. It is off, and no billing exists.