unix-docs — 4.2BSD, cross-referenced. Ask it anything.

You're reading this over a network stack whose ideas were first written, in 1983, inside the file you'll find in five seconds with this tool: sys/netinet/tcp_input.c.

The whole 4.2BSD kernel and userland — 3,198 files, 681 manual pages, 152 system calls — indexed, cross-referenced, and served to your AI agent over MCP. Every answer comes with a path:line citation from a real index. Nothing is recalled from memory. Nothing is guessed.

Don't guess what 4.2BSD does. Ask it.

The kernel your internet grew up on

In 1983, a group at Berkeley ran a VAX 11/780 and shipped the release that invented the modern network stack: the BSD socket API, TCP/IP as we know it, socket(), connect(), the mbuf. Every connection you make today runs on decisions first made in this tree.

That tree — complete, with all of its period-correct warts — is in this repository. Not a mirror to download. Not a rendering. The source, ingested and cross-referenced so you can read it like a system:

• The complete 4.2BSD source tree — sys/ kernel and src/ userland, 3,198 C/assembly/header files (~23 MB)

• All 681 manual pages — sections 1–8, l, n, o, nroff-cleaned to plain text

• The 4.2BSD System Manual, Networking Implementation Notes, and USENIX supplements

• The full syscall table — with argument counts and kernel handlers, parsed from the actual switch table

The reachable proof it's real: a new 4.2BSD program — jot, written in period-correct K&R C — compiled and run inside a booted 4.2BSD VAX emulator. Scroll down; the output is there.

Related MCP server: mcp-docs

Watch it work

Read a whole data structure instead of one grep line:

read_definition({ symbol: "mbuf", path_filter: "sys/h" })
→ ===== sys/h/mbuf.h:28-35 =====
     28 struct mbuf {
     29 	struct	mbuf *m_next;		/* next buffer in chain */
     30 	u_long	m_off;			/* offset of data */
     31 	short	m_len;			/* amount of data in this mbuf */
     ...

Find your way around a subsystem you've never seen:

list_source_files({ path: "sys/netinet" })
→ ===== sys/netinet =====
  sys/netinet/tcp_input.c  (934 lines)
  sys/netinet/tcp_output.c  (333 lines)
  ... 33 files in all

Search for an exact string a keyword index can't express:

grep_source({ pattern: "m->m_len", context: 1 })
→ sys/net/raw_usrreq.c-47- 	m->m_next = m0;
  sys/net/raw_usrreq.c:48: 	m->m_len = sizeof(struct raw_header);

Resolve a header the way the 4.2BSD compiler would:

resolve_include({ name: "<sys/mbuf.h>" })
→ sys/h/mbuf.h  (113 lines) — <sys/...> is the kernel header directory sys/h

Get the whole story on a system call — note that exit is implemented by rexit() in the kernel, a name you would never have guessed:

get_syscall({ name_or_number: "1", include_manpage: false })
→ #1 exit

  ## Switch table
  sys/sys/init_sysent.c:107: 1 argument, implemented by rexit()

  ## Kernel implementation
  sys/sys/kern_exit.c:23: rexit()

  ## libc stub
  src/lib/libc/vax/sys/_exit.c

  ## Manual page
  exit(2) - terminate a process

18 tools, one reference

Every access path you need is a tool, and every tool tells the agent when to use it:

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

• apropos — search names and NAME-section descriptions, like apropos(1)

• search_manpages — ranked full-text search, optionally restricted to a section

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

Source code

• list_source_files — browse a directory, like ls(1)

• search_source — ranked keyword search; files carrying every term rank first

• grep_source — exact substring or regex search with context

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

• find_symbol — case-sensitive lookup of definitions, declarations, references

• read_definition — a symbol's whole definition: function body, struct body, or macro

• resolve_include — map <sys/mbuf.h> to its file in the tree

System calls

• list_syscalls — the table, with argument counts and kernel handlers

• get_syscall — a full dossier for one call: table entry, switch table, kernel implementation, libc stub, and man page

Across everything

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

Choosing between the search tools

The corpus is also exposed as MCP resources — enumerable, fetchable URIs:

…and three prompts for common 4.2BSD work: trace_syscall (follow a call from the libc stub into the kernel), kernel_subsystem_tour (survey a kernel directory), and write_utility (write a program in period-correct K&R C, verifying every library routine against the tree).

Proof it's real: a program compiled and run on 4.2BSD

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

demo/sim42.py and demo/emulator-jot.py boot a real 4.2BSD VAX 11/780 on an Open SIMH emulator, transfer jot.c, compile it with the 4.2BSD C compiler, and run a demonstration suite:

$ 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 whole cycle is unattended — sim42.py drives the emulator console over a PTY, handling the kernel's automatic-reboot halts and csh's here-doc quirks. This is not a screenshot of the past; it is a system you can still compile against.

demo/syscall-dossier.mjs shows the corpus doing its job: a small MCP client that assembles a fully-cited dossier for any syscall — table entry, man page, kernel routine, callers, and related prose — in one run:

$ node demo/syscall-dossier.mjs socket
## 1. The call
> MCP: get_syscall("socket", include_manpage: true)
#97 socket
sys/sys/init_sysent.c:203: 3 arguments, implemented by socket()
sys/sys/uipc_syscalls.c:24: socket()
src/lib/libc/vax/sys/socket.c
socket(2) - create an endpoint for communication

Get it running in two minutes

git clone https://github.com/runit-xze/unix-docs-mcp
cd unix-docs-mcp
yarn
yarn start          # launch the MCP server over stdio
yarn test           # run the test suite (57 passing)

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"]
    }
  }
}

Memory is honest: the server lazy-loads each corpus on first use. Indexing the full source tree takes ~1.7 s and brings resident memory to ~390 MB (the man-page corpus adds ~20 MB). Clients that only use the man pages never build the source index. If you run many MCP servers in one session, keep this in mind when sizing the host.

Under the hood

scripts/ingest.mjs builds the prose corpus from OCR'd PDFs. scripts/ingest-dev.mjs builds the man page, source, and syscall corpora from a 4.2BSD distribution. Two things are derived at runtime rather than baked into data/, so they can never drift from the committed tree: the argument counts and kernel handlers come from parsing sys/sys/init_sysent.c, and the apropos descriptions come from the NAME section of each man page.

The cross-reference index (find_symbol, read_definition) is what makes this different from a pile of text: a symbol's definitions, declarations, and every reference, ranked and path:line-cited, so an agent can answer "what calls tcp_input" by reading, not by guessing.

Build on it

This project's own code is dedicated to the public domain under CC0 — take it, adapt it, ship it. The bundled 4.2BSD material is a different story; see the license section.

Good first contributions: new ingest targets, better symbol classification, and demos that push the emulator further. The test suite is 57 tests and the e2e test drives the real stdio protocol.

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 carries a mix of Berkeley and AT&T copyrights and has no single clean license; see LICENSE.data for the details, the TUHS 4.2BSD distribution for provenance, and the individual file headers for the applicable terms.