mcp-secure-builder

Small slices so the security model stays easy to understand. Package name on npm: mcp-secure-builder.

This repo is built in small slices so the security model stays easy to understand.

Builder rules (friendly + safe)

Slice 1 — Policy is required

• Every tool must declare a policy.
• Missing policy = blocked (deny-by-default).

Why: prevents tools from silently shipping without guardrails.

Slice 2 — Timeout

• Tools have a timeout (timeoutMs).
• Slow tools fail fast instead of hanging the server.

Why: reliability and DoS-resistance.

Slice 3 — Output cap

• Tool output is capped (maxOutputBytes).
• This protects context size, cost, and reduces accidental data dumping.

Why: tools often return content that ends up in the model context.

Local master key (stdio-friendly)

For tools that should not run unless the server is “configured”, use requireLocalKey: true in policy.

• Set MCP_LOCAL_KEY in the server environment (at least 8 characters).
• Cursor stdio: put MCP_LOCAL_KEY in your MCP server env config so only your machine/session has the key.
• If you pass ctx.localKey or Authorization: Bearer ..., it must match MCP_LOCAL_KEY (optional stricter check).
• If you do not pass a key in ctx, we only require that MCP_LOCAL_KEY is set on the process (simple “server must be configured” gate).

Search (opt-in)

Search is powerful and higher-risk, so it is opt-in:

• Search is disabled by default.
• Mark a tool as search with capability: "search".
• To enable search tools, create the builder with enableSearch: true.

Search output default cap

• Normal tools default to a smaller output cap.
• Search tools default to 64KB output cap if maxOutputBytes is not set.

Paging (safe + easy to remember)

For search results, prefer paging so each call stays small:

• Input: limit, pageToken
• Output: results, nextPageToken

This avoids giant outputs and prevents clients from requesting extreme offsets.

Slice 5 — Scaffold a stdio server (CLI)

Default (after publishing): the template uses mcp-secure-builder from npm (^0.1.0 or current version in this repo’s package.json).

npx -p mcp-secure-builder create-mcp-server --name my-mcp-server --out .
# or from a clone of this repo:
node ./scripts/create-mcp-server.mjs --name my-mcp-server --out .

Contributors hacking this repo locally should link the workspace:

node ./scripts/create-mcp-server.mjs --name my-mcp-server --out . --link-local

That writes file: URL dependency to this checkout instead of semver.

Then:

cd my-mcp-server
npm install
npm run build
npm start

After npm link or global install of this package, you can run create-mcp-server on your PATH.

Publish mcp-secure-builder to npm

1. Create an npm account and log in: npm login
2. From this repo: npm publish
   • prepublishOnly runs tests first.
3. Consumers: npm install mcp-secure-builder and use the scaffold default (no --link-local).

If the package name is taken, change "name" in package.json and publish under your scope, e.g. @youruser/mcp-secure-builder.

Slice 6 — MCP Registry (publish metadata)

The registry hosts metadata (not your server binary). Publishing flow is usually:

1. Publish your npm package (if you use npm as the artifact source).
2. Create/update server.json (official tool: mcp-publisher init).
3. Authenticate (mcp-publisher login ...).
4. Publish metadata (mcp-publisher publish).

This repo includes a small helper mcp-registry that:

• downloads the official mcp-publisher binary (cached under ~/.cache/sellapp-mcp), and
• forwards init, login, publish
• adds validate with a basic server.json shape check (not a full registry gate)

Examples:

# Basic local validation (fast)
npm run registry -- validate .

# Official CLI (interactive / network)
npm run registry -- init .
npm run registry -- login github
npm run registry -- publish .

GitHub Actions automation (OIDC) is documented upstream:
https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/github-actions.mdx

Run tests

npm install
npm test