code-skeleton-mcp

MCP server that returns code outlines (classes, functions, signatures, docstrings) instead of full file contents. On a 2000-line file, get_outline typically produces ~80 lines of output — roughly 40x fewer tokens than reading the whole file with Read.

Supported languages out of the box: Python, Go, TypeScript, JavaScript (plus TSX). Uses tree-sitter grammars compiled to WebAssembly, so there is no native compilation step — it installs cleanly via npx on macOS (Apple Silicon / Intel), Linux, and Windows.

Tools

Tool	What it returns
get_outline	File or directory outline: classes, methods, functions, constants, first-line docs.
get_function	Source of a single function/method by dotted path (e.g. User.greet).
get_class	A class/interface/struct with method signatures (bodies optional).
get_imports	Parsed imports with isStdlib / isThirdParty / isRelative flags and best-effort relative-path resolution.

Quick setup

One command wires the server into your AI tool and adds CLAUDE.md rules that teach the agent when to prefer these tools over Read:

npx code-skeleton-mcp setup             # interactive, target: claude-code
npx code-skeleton-mcp setup --yes       # non-interactive
npx code-skeleton-mcp setup --dry-run   # preview only
npx code-skeleton-mcp setup --uninstall # clean removal

What it does for --target claude-code:

• Appends a rules block to ~/.claude/CLAUDE.md (wrapped in <!-- code-skeleton-mcp:rules:start/end --> markers — re-runs update in place, --uninstall removes cleanly without touching anything else).
• Registers the server under ~/.claude.json → mcpServers["code-skeleton"] as npx -y code-skeleton-mcp (other servers are preserved).

Flags:

Flag	Effect
--target <id>	Comma-separated target IDs. Default claude-code. all → all.
--rules-only	Skip MCP registration.
--mcp-only	Skip CLAUDE.md rules.
--uninstall	Remove instead of install.
--dry-run	Preview paths and changes without writing.
--yes, -y	Don't prompt for confirmation.

Currently supported targets: claude-code. Planned: claude-desktop, cursor, codex, qwen — contributions welcome (each is one InstallTarget class in src/adapters/targets/).

Restart your AI tool after setup; the four tools appear with the mcp__code-skeleton__ prefix.

Install (without setup)

npm install -g code-skeleton-mcp
# or one-off:
npx code-skeleton-mcp outline path/to/file.py

Manual MCP entry (if you don't want to use setup):

{
	"mcpServers": {
		"code-skeleton": {
			"command": "npx",
			"args": ["-y", "code-skeleton-mcp"]
		}
	}
}

CLI

The same binary works as a CLI for debugging (JSON on stdout):

code-skeleton-mcp outline src/app.py --depth 2
code-skeleton-mcp outline src/ --recursive
code-skeleton-mcp function src/app.py User.greet
code-skeleton-mcp class src/app.ts User --bodies
code-skeleton-mcp imports src/app.ts
code-skeleton-mcp setup --dry-run

Run without arguments to start the MCP server on stdio.

get_outline input

Field	Type	Default	Notes
path	string	—	File or directory.
max_depth	integer	2	Nesting depth of symbols returned.
include_docstrings	boolean	true	Include first line of docstrings / JSDoc / Go docs.
include_private	boolean	false	_name, Go lowercase, TS private.
recursive	boolean	false	If path is a directory, walk subdirectories.

Example

$ code-skeleton-mcp outline tests/fixtures/go/sample.go --depth 2
{
  "path": "tests/fixtures/go/sample.go",
  "language": "go",
  "symbols": [
    { "kind": "constant", "name": "MaxRetries", "line": 13, "signature": "const MaxRetries = 3",
      "docstring": "MaxRetries is the default retry cap." },
    { "kind": "struct", "name": "User", "line": 18, "signature": "User struct { ... }",
      "docstring": "User is a user record.",
      "children": [
        { "kind": "method", "name": "Greet", "line": 36, "signature": "func (u *User) Greet() string",
          "docstring": "Greet returns a greeting." }
      ] },
    ...
  ]
}

Architecture

Vertical Slice + Hexagonal (Ports & Adapters).

• src/domain/ — pure types: CodeSymbol, Outline, ImportRef, Language, domain errors. No external dependencies.
• src/ports/ — ParserPort, FileSystemPort, CachePort, InstallTarget.
• src/adapters/ — tree-sitter WASM parser (+ per-language strategies under parser/strategies/), Node fs, in-memory cache, install targets under targets/.
• src/features/ — one vertical slice per MCP tool and per CLI feature: schema.ts (Zod) + usecase.ts (port orchestration) + handler.ts (MCP callback, when applicable).
• src/composition-root.ts — single wiring point.
• src/mcp-server.ts / src/cli.ts / src/index.ts — MCP stdio entry, CLI dispatcher, and the bin entry that routes between them.
• wasm/ — precompiled tree-sitter grammars (committed, not fetched at install).
• queries/ — upstream tags.scm + local augment queries per language.

Adding a new AI-tool target (Cursor, Codex, Qwen, Claude Desktop, …) is one file in src/adapters/targets/ implementing InstallTarget, plus one line in registry.ts.

Development

npm ci
npm run lint          # eslint .
npm run typecheck     # tsc --noEmit
npm test              # vitest run
npm run build         # tsc -p tsconfig.build.json

Refresh wasm grammars and upstream tags.scm (only when bumping grammar versions):

npm run fetch-wasm

License

MIT