unix-docs-mcp
The server provides access to historical 4.2BSD UNIX documentation, manual pages, source code, and system calls through 13 tools.
Documents: Browse the three included prose documents (System Manual, Networking Implementation Notes, USENIX Supplementary Documents), view metadata and tables of contents, full-text search with snippets, and read specific page ranges.
Manual pages: List all 681 man pages (filterable by section), search across them, and read any page by name and section.
Source code: Grep-style search with path filtering, read files or line ranges, and locate symbol definitions, declarations, and references.
System calls: Browse the 152-entry syscall table and look up details by name or number.
Cross-corpus: Search simultaneously across documents, man pages, and source code, with results grouped by type.
It operates over stdio for MCP client integration; demos include a syscall dossier generator and running period-correct utilities on a 4.2BSD emulator.
Provides tools for searching and reading historical 4.2BSD documentation, manual pages, and source code, including system call information.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@unix-docs-mcp what's the man page for read(2)?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 andsrc/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 allSearch 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/hGet 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 process18 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 documentsget_document_info— metadata plus a page-by-page overviewsearch_documents— ranked full-text search with snippetsread_pages— read a page or range of pages
Manual pages
list_manpages— list pages, optionally by sectionapropos— search names and NAME-section descriptions, likeapropos(1)search_manpages— ranked full-text search, optionally restricted to a sectionread_manpage— full text of a page, e.g.read(2)
Source code
list_source_files— browse a directory, likels(1)search_source— ranked keyword search; files carrying every term rank firstgrep_source— exact substring or regex search with contextread_source_file— read a file or a line range, with line numbersfind_symbol— case-sensitive lookup of definitions, declarations, referencesread_definition— a symbol's whole definition: function body, struct body, or macroresolve_include— map<sys/mbuf.h>to its file in the tree
System calls
list_syscalls— the table, with argument counts and kernel handlersget_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
You want | Use |
The page that documents a concept |
|
Every page that mentions a term |
|
Where an idea lives in the source |
|
An exact string, or a regex |
|
Where a symbol is defined and used |
|
To read the code of a definition |
|
The corpus is also exposed as MCP resources — enumerable, fetchable URIs:
URI | Contents |
| index of the prose documents |
| the syscall table, with argument counts and handlers |
| one manual page, e.g. |
| one page of a prose document |
| one source file, e.g. |
…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 1The 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 communicationGet 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/, anddemo/— 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.
Available Tools
13 toolsfind_symbolFind a symbol in 4.2BSD sourceA
Locate a function, struct, macro, typedef, or variable across the 4.2BSD source. Definitions are listed first, then declarations and references, each as path:line: code.
Inputs: symbol (required), max_results, path_filter.
get_document_infoDocument info and page overviewA
Return metadata for one document plus a page-by-page overview (first line of each page), useful as a table of contents before reading specific pages.
Inputs: doc_id (required).
get_syscallLook up a system callA
Look up a 4.2BSD system call by number or name (e.g. "2" or "fork"). Returns its number, name, and any notes.
Inputs: name_or_number (required).
list_documentsList ingested documentsA
List the historical UNIX documents available on this server, with metadata such as title, authors, source URL, page count, and a short description.
Inputs: no named parameters.
list_manpagesList man pagesA
List the 4.2BSD manual pages, optionally restricted to a section (1=commands, 2=syscalls, 3=libc, 4=devices, 5=formats, 6=games, 7=documents, 8=admin, l=local, n=new, o=obsolete).
Inputs: limit, section.
list_syscallsList 4.2BSD system callsA
List the 4.2BSD system call table (number, name, and any notes). Optionally filter by name substring.
Inputs: filter.
read_manpageRead a manual pageA
Read the full text of one 4.2BSD manual page by name and optional section (e.g. name="read", section="2"). If the name is ambiguous across sections, give the section.
Inputs: name (required), section.
read_pagesRead document pagesA
Read raw text of one page or a contiguous range of pages from a document. Use get_document_info first to find the right pages.
Inputs: doc_id (required), start_page (required), end_page.
read_source_fileRead a 4.2BSD source fileA
Read a source file from the 4.2BSD tree by path (e.g. "sys/sys/sysent.c" or "src/lib/libc/gen/read.c"). Optionally restrict to a line range. At most 1500 lines are returned.
Inputs: path (required), end_line, start_line.
search_allSearch everythingA
Search across all corpora at once: prose documentation, manual pages, and source code. Results are grouped by kind and labeled.
Inputs: query (required), max_results.
search_documentsFull-text searchA
Search the ingested UNIX documentation. Returns ranked page-level matches with a snippet around the first hit. Optionally restrict to a single document by doc_id.
Inputs: query (required), doc_id, max_results.
search_manpagesSearch manual pagesA
Search the 4.2BSD manual pages. Returns ranked matches with a snippet around the first hit. Restrict with section (2=syscalls, 3=libc, 4=devices, 5=formats).
Inputs: query (required), section, max_results.
search_sourceSearch 4.2BSD source codeA
Search the 4.2BSD kernel and userland C source. Returns matching lines in the style of grep (path:line: code). Optionally filter by a path substring such as "netinet" or "libc/gen".
Inputs: query (required), max_results, path_filter.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct corpus (documents, manpages, source, syscalls) with distinct actions (list, get, search, read, find). The descriptions clearly differentiate between search_documents, search_manpages, and search_source, so there is no real ambiguity.
All tool names follow a consistent verb_noun snake_case pattern (list_, get_, search_, read_, find_). Even search_all fits the verb+noun pattern with 'all' as the object. No mixed naming conventions are present.
13 tools is well-scoped for a multi-corpus documentation server. Each corpus (documents, manpages, source, syscalls) has just the right set of operations, and search_all provides a cross-corpus entry point. No redundant tools exist.
The tool set covers the full read-only lifecycle for documents (list/get/search/read), manpages (list/search/read), source (search/read/find), and syscalls (list/get). A minor gap is the lack of a directory listing for source files, but search_source and find_symbol partially mitigate this.
Related MCP Connectors
MCP server for opencode documentation, generated by doc2mcp.
MCP server for manus documentation, generated by doc2mcp.
Remote MCP server for Tandem docs, install guides, SDKs, workflows, and agent setup help.
MCP server for innovationlab documentation, generated by doc2mcp.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA tutorial MCP server for learning the Model Context Protocol by building file and system tools. Provides hands-on experience creating custom tools that enable AI models to interact with files and execute system commands.-
- AlicenseNot gradedqualityDmaintenanceGeneric MCP server that exposes Markdown documentation to LLMs, enabling them to search and answer questions about any software documentation.MIT
- FlicenseNot gradedqualityDmaintenanceMCP server providing filesystem operations, shell execution, and web search capabilities.-
- AlicenseAqualityCmaintenanceMCP server to access and search adonis-mcp documentation files from GitHub, with tools for listing, searching, and extracting code examples.3101 npm1MIT