unix-docs MCP

An MCP server for working with historical UNIX documentation and source code, focused on development for 4.2 BSD.

Serves a single VAX/4.2BSD-focused reference over stdio: the prose manuals, the complete manual pages, and — yes — the full 4.2BSD source tree, all ingested into this repository.

What's in this repo

The full 4.2BSD source code is intentionally committed to this repository so the project is self-contained — no need to download distribution tarballs to use the source tools. Source and documentation are from the TUHS 4.2BSD distribution; BSD-derived code and documentation are freely redistributable.

Related MCP server: mcp-docs

Tools

The server registers 13 tools over stdio:

Documents

• list_documents — list the prose documents

• get_document_info — metadata plus a page-by-page overview

• search_documents — ranked full-text search with snippets

• read_pages — read a page or range of pages

Manual pages

• list_manpages — list pages, optionally by section

• search_manpages — ranked search (optionally restricted to a section, e.g. 2 = syscalls)

• read_manpage — full text of a page, e.g. read(2)

Source code

• search_source — grep-style search returning path:line: code

• read_source_file — read a file or a line range with line numbers

• find_symbol — locate definitions, declarations, and references for a symbol

System calls

• list_syscalls — the syscall table, optionally filtered

• get_syscall — look up a syscall by number or name

Across everything

• search_all — one query across documents, man pages, and source

Usage

npm install
npm start          # launch the MCP server over stdio
npm test           # run the test suite
npm run ingest     # rebuild all corpora from raw sources in ../raw

Configure it as an MCP server for any MCP client, e.g. in opencode.json:

{
  "mcp": {
    "unix-docs": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/unix-docs-mcp/src/index.js"]
    }
  }
}

Development example

Search the kernel source for the TCP input path:

search_source({ query: "tcp_input", path_filter: "netinet" })
→ sys/netinet/tcp_input.c:98: tcp_input(m, ifp)

Look up the read syscall:

get_syscall({ name_or_number: "read" })
→ #3 read

Find where mbuf structures are defined:

find_symbol({ symbol: "sockaddr" })
→ [definition] src/etc/routed/af.c:107: ...

Ingest

scripts/ingest.mjs builds the prose corpus from OCR'd PDFs in ../raw. scripts/ingest-dev.mjs builds the man page, source, and syscall corpora from a 4.2BSD distribution extracted to ../raw/42bsd/ (kernel under srcsys/, userland under src/).

License

Two different licenses apply to different parts of this repository:

• This project's own code — the server, library, script, test, and demo files under src/, scripts/, test/, and demo/ — is dedicated to the public domain under CC0 1.0 Universal.

• The bundled 4.2BSD material under data/ (source code, man pages, and prose documentation) is not covered by the CC0 dedication. It is BSD-derived and retains its own licensing; see the TUHS 4.2BSD distribution and the individual file headers for the applicable BSD terms.