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

Path	Contents
data/index.json + data/*.txt	Three prose documents: 4.2BSD System Manual, 4.2BSD Networking Implementation Notes, and the USENIX UNIX User's Manual Supplementary Documents
data/man.json	681 manual pages from the 4.2BSD distribution (sections 1–8, l, n, o), nroff cleaned to plain text
data/source/	The complete 4.2BSD source tree — 3,198 C/assembly/header files (~23 MB): the sys/ kernel (including netinet/ TCP/IP), and the src/ userland (lib/libc, bin, usr.bin, ucb, ...)
data/syscalls.json	The 4.2BSD system call table (152 entries), parsed from sys/sys/syscalls.c
src/	Server and library code
scripts/	Ingest scripts that build the corpora
test/	Unit + end-to-end tests (20 passing)
demo/	Showcase demos: an MCP-client syscall dossier, and a new 4.2BSD userland utility (jot) built and run inside a real 4.2BSD emulator

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.

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: ...

Demos

The demo/ directory contains two showcase pieces that exercise the corpus and the real operating system.

Syscall dossier (MCP client)

demo/syscall-dossier.mjs is a small MCP client that drives the server over stdio and assembles a fully-cited dossier for any syscall: the syscall table entry, the manual page, the kernel implementation (via find_symbol + read_source_file), and related prose. Run it with node demo/syscall-dossier.mjs <syscall>:

$ node demo/syscall-dossier.mjs socket
#97 socket

## 2. Manual page (section 2)
> MCP: read_manpage("socket", "2")
SOCKET(2)
NAME
socket - create an endpoint for communication
...

## 3. Kernel implementation
> MCP: find_symbol("socket", path_filter: "sys/sys")
[definition] sys/sys/uipc_syscalls.c:24: socket()
> MCP: read_source_file("sys/sys/uipc_syscalls.c", 21, 60)
   24 socket()
   25 {
   26 	register struct a { int domain; int type; int protocol; } ...

New 4.2BSD userland utility: jot

demo/jot.c is a new program written for 4.2BSD in period-correct K&R C — no ANSI headers (4.2BSD has none), no getopt, explicit old-style declarations. jot prints sequential or random data and first shipped in 4.3BSD, so it is a natural addition to a 4.2BSD system:

jot [ reps [ begin [ stop [ step ]]]]
	jot -r [ reps [ begin [ stop ]]]
	jot -c [ reps [ begin [ stop ]]]
	jot -b word [ reps ]
	jot -w word [ reps [ begin [ stop [ step ]]]]
	jot -s sep [ reps [ begin [ stop [ step ]]]]
	jot -p prec [ reps [ begin [ stop [ step ]]]]

demo/sim42.py and demo/emulator-jot.py bring up a 4.2BSD VAX emulator, transfer jot.c to it, compile it with the 4.2BSD C compiler, and run a demonstration suite. This verifies the program against the real system:

$ python3 demo/emulator-jot.py
== compiling with 4.2BSD cc ==
-rwxrwxr-x  1 root        10240 Aug  4 23:39 /tmp/jot
$ /tmp/jot 5                    ->  1 2 3 4 5
$ /tmp/jot 8 1 8 -s ' '         ->  1 2 3 4 5 6 7 8
$ /tmp/jot -c 5 97              ->  a ` _ ^ ]
$ /tmp/jot -r 4 1 10            ->  4.74837 9.21693 9.57097 7.52004
$ /tmp/jot -b hello 3           ->  hello hello hello
$ /tmp/jot -w "n=%g;" 4 1 2 0.25 ->  n=1; n=1.25; n=1.5; n=1.75;
$ /tmp/jot -p 2 4 0 1 0.3       ->  0 0.3 0.6 0.9
$ /tmp/jot 4 4 1                ->  4 3 2 1

The emulator is an Open SIMH VAX 11/780 running 4.2BSD from a disk image in ~/bsd42/. sim42.py drives the emulator console over a PTY (the kernel's automatic-reboot halts and csh's here-doc quirks are handled), so the whole cycle is unattended. demo/boot-console.ini is the emulator configuration used; it boots the installed disk with the console on stdin/stdout.

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.