mapnostics-mcp

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

• Go to mapnostics.com
• Open your repo → Settings → API keys
• 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_..."

Available tools

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

Tool	Extra arguments	What it does
get_repo_health	—	Health score, dead code count, tech debt hours
get_health_score	—	Composite score with per-dimension breakdown
get_dead_code	file_path?	Dead code entities with evidence and confidence
get_zombie_code	—	Zombie entities with call-chain relationships
get_impact	file_path	Blast radius for a file change
get_dependencies	file_path?	File import/dependency graph
get_coupling	file_path	Coupling level and incoming/outgoing counts
get_bus_factor	—	Key-person risk: bus factor, risk band, per-contributor ownership, orphaned modules
find_in_codebase	query	Search file paths, routes and tables by substring
resolve_operational_truth	entity_id	Full reasoning trace for one entity
get_intent	file_path?	AI-recovered intent for the repo or a file
detect_secrets	severity?	Hardcoded secret findings from the latest scan
get_onboarding	—	Entry points, learning path, gotchas
analyse_ticket	ticket_id, source	Effort estimate, related files, approach
get_similar_fixes	file_path	Past tickets resolved in similar files

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

Configuration

Variable	Flag	Required	Default
MAPNOSTICS_API_KEY	--key	Yes	—
MAPNOSTICS_URL	--url	No	https://www.mapnostics.com/api/mcp

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

cd packages/mapnostics-mcp
npm install
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
brew install mcp-publisher   # or: go install github.com/modelcontextprotocol/registry/cmd/mcp-publisher@latest

cd packages/mapnostics-mcp
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