@sammons/code-outline-mcp

A stdio MCP (Model Context Protocol) server that exposes the code-outline CLI as tools. The server spawns the installed code-outline binary and returns its output over the MCP protocol.

How it works

This server wraps @sammons/code-outline-cli by spawning the installed binary as a subprocess. It does not reimplement any parsing logic. Each tool call runs code-outline once per glob pattern and returns the combined output.

Install

pnpm add -g @sammons/code-outline-mcp

Register with Claude Code

claude mcp add code-outline -- code-outline-mcp

Generic stdio client config

Most MCP clients read a config shaped like this:

{
  "mcpServers": {
    "code-outline": {
      "command": "code-outline-mcp",
      "args": []
    }
  }
}

Protocol contract

stdout carries only newline-delimited JSON-RPC 2.0 response lines. Nothing else writes to stdout. All logs go to stderr as structured JSON lines. A client that pipes stdout into a JSON-RPC parser never sees a stray log line.

Tools

outline

Produces a code outline for one or more glob patterns. Runs the code-outline CLI once per pattern and concatenates the results.

Input schema:

| Field | Type | Required | Default | Notes | |---|---|---|---|---| | patterns | string[] | yes | — | One or more glob patterns. Minimum length 1. | | format | 'llmtext' \| 'json' \| 'yaml' \| 'ascii' | no | llmtext | Output format. | | depth | integer >= 0 | no | — | Maximum AST depth to traverse. | | all | boolean | no | — | Show all nodes, including unnamed ones. | | cwd | string | no | server process cwd | Working directory to resolve patterns against. |

Response shape: { content: [{ type: 'text', text: string }], isError: boolean }. isError is true when any per-pattern invocation exits non-zero; the response text then includes a --- stderr for <pattern> --- block for each failing invocation.

WARNING: the installed @sammons/code-outline-cli (pinned ^2.1.1) accepts only one positional pattern argument per invocation — passing more than one silently drops every pattern after the first, with no warning printed. This is why the server invokes the CLI once per pattern and concatenates the results itself, instead of passing every pattern to a single invocation. A future CLI release may add real multi-positional support; the per-pattern loop stays correct either way.

code_outline_version

No input. Runs code-outline --version and returns the version string.

Response shape: { content: [{ type: 'text', text: string }], isError: boolean }.

Development

pnpm install
pnpm check   # biome + tsc --noEmit + unit tests (90% coverage gate) + e2e

pnpm build emits to dist/. pnpm test runs the unit suite. pnpm test:e2e builds then spawns dist/main.js as a real subprocess against the real installed CLI.

Releasing

See RELEASING.md.