Mapnostics MCP

MCP server for Mapnostics codebase intelligence. Connects Claude Code, Claude Desktop, Cursor, Windsurf, Zed, and any MCP-compatible client to your Mapnostics codebase analysis: dead code, impact simulation, intent recovery, health score, secrets findings, ticket analysis, and onboarding guides.

This package is a thin stdio bridge. It forwards newline-delimited JSON-RPC from your editor to the streamable-HTTP endpoint with your API key attached, and writes replies back to stdout. It has no runtime dependencies, and because it forwards messages verbatim, new server-side tools appear automatically without a CLI upgrade.

Setup

Get your API key

1. Go to mapnostics.com

2. Open your repo → Settings → API keys

3. Create a new key (starts with mns_)

Claude Code (.mcp.json in project root)

{
  "mcpServers": {
    "mapnostics": {
      "command": "npx",
      "args": ["mapnostics-mcp"],
      "env": {
        "MAPNOSTICS_API_KEY": "mns_your_key_here"
      }
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

Same format as above.

Cursor (.cursor/mcp.json)

Same format as above.

Clients with native streamable-HTTP support

Skip the bridge entirely and connect directly:

URL:    https://www.mapnostics.com/api/mcp
Header: Authorization: Bearer mns_...

For Claude Code:

claude mcp add --transport http mapnostics https://www.mapnostics.com/api/mcp \
  --header "Authorization: Bearer mns_..."

Related MCP server: sourcebook

Available tools

Every tool takes repo_id (the repository UUID from Mapnostics). Additional arguments are listed below.

analyse_ticket reads cached analysis. If it returns nothing, open the ticket in the Mapnostics UI once to populate the cache.

Configuration

Flags take precedence over environment variables:

MAPNOSTICS_API_KEY=mns_... npx mapnostics-mcp
npx mapnostics-mcp --key mns_... --url http://localhost:3000/api/mcp

Troubleshooting

"no API key" — the key is unset. In editor configs it belongs in the env block, not args.

"Unauthorized — check your MAPNOSTICS_API_KEY" — the key was revoked or mistyped. Create a fresh one under Settings → API keys.

"Failed to reach ..." — the endpoint is unreachable. Check network access, or point --url at your local dev server.

Publishing (maintainers)

npm

npm install
npm run build
npm publish   # prepublishOnly runs the TypeScript build

The mcpName field in package.json must match the name in server.json (io.github.ffteema/mapnostics-mcp) — the MCP registry checks the published package for it before it will accept the packages entry.

Model Context Protocol registry

server.json in this directory is the registry manifest. It declares both the npm bridge (stdio) and the hosted endpoint (remotes, streamable-http), so a client that speaks HTTP natively skips the bridge.

# one-time: install the publisher CLI

mcp-publisher login github          # authenticates the io.github.ffteema/* namespace
mcp-publisher publish               # validates and submits server.json

Bump version in both server.json and package.json for each release, then re-run npm publish and mcp-publisher publish.

License

MIT