mcp-surface-lint

# mcp-surface-lint

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

This is a monorepo:

| Package | What it is |
| --- | --- |
| [`packages/core`](packages/core) | The linter — 19 rules, the scoring engine, and the `mcplint` CLI (`mcp-surface-lint` on npm). Publishable to npm. |
| [`apps/web`](apps/web) | The hosted playground: paste a `tools/list` dump or point it at a remote MCP URL, get a score and an audit. |

## Quick start

```bash
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`](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:

```bash
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:

```bash
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`](DEPLOYMENT.md).

## The CLI

```bash
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`](packages/core/README.md) for the full CLI, config, and scoring model,
and [`packages/core/docs/rules.md`](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`](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.