pghacker-mcp answers questions about PostgreSQL's design history and source code, with citations. Ask why a feature works as it does, or what happened to SQL/PGQ, and an agent finds the pgsql-hackers threads, commits and code that answer it, and quotes them.
The project is powered by PostgreSQL itself. The mail, the graph and PostgreSQL's full commit history, live in Azure HorizonDB (PostgreSQL when run locally), and PostgreSQL indexes do the searching: trigram for code and text, vector for semantic search, BM25 for full-text search, and B-trees over the history's commit ranges, with Apache AGE for the graph. Typical searches across the whole commit history return in milliseconds.
You need Node.js 24 or later, Rust (the toolchain in rust-toolchain.toml), and Docker with Docker Compose, on macOS or Linux.
npm run setup # download PilotSwarm, install dependencies, build, and create .env
npm start # start PostgreSQL, both services, PilotSwarm's worker and portal, and the home page
npm run load # load two months of pgsql-hackers and PostgreSQL's commit historynpm start runs the app in the background (--foreground keeps it in the terminal), logging to .runtime/logs/; the first start builds the Rust services, which takes a few minutes. npm run stop stops it and keeps the data. npm run load loads the data (see Load the data). Then add the MCP URL from the home page to your agent; Use it lists the tools.
| What | Address |
|---|---|
| The home page: the MCP URL, how to add it to an agent, and examples | http://127.0.0.1:3001 |
| The portal, to chat with the agents | http://127.0.0.1:3001/portal/ |
| pghacker-mcp, for your MCP client | http://127.0.0.1:3102/mcp, or http://127.0.0.1:3001/mcp |
| pghacker-indexer, for the crawler agents | http://127.0.0.1:3101/mcp |
| PostgreSQL 17 | 127.0.0.1:55433 |
Everything listens on 127.0.0.1 only, and the portal has no sign-in, so don't expose it.
The MCP tools need no language model. Only the portal's agents and extraction (npm run crawl) do: set GITHUB_TOKEN in .env or your shell for GitHub Copilot's models, or add another provider in the portal's Admin Console. For semantic search, set the embedding settings, HORIZON_EMBED_*, in .env (.env.example shows them); without them, the mail searches use full text only. The reference lists every setting.
Locally, pghacker-mcp works on a slice of the data. npm run load loads it, and starts the app first if it isn't running:
npm run load # the mail, then PostgreSQL's whole commit history
npm run load -- --quick # the mail, and the history of src/backend/parser onlyIt shows its progress and ends with what to do next. The first load takes about 15 minutes. Run it again at any time: it skips what's done. --mail-only and --code-only load one part, and --force rebuilds the history. The reference shows how to do each step by hand.
-
Mail. Two months of pgsql-hackers, June–July 2026 (about 5,500 messages), and 14 whole threads on SQL/PGQ and SQL/JSON (
config/test-slices.toml). -
Code. PostgreSQL's whole commit history, every branch, tag and commit, from git.postgresql.org. The indexer applies new commits every hour.
-
Extraction. Features, decisions and authors' positions, which
search_extractsandauthor_perspectiveread, come from crawler agents. They need a language model: add a token withecho "GITHUB_TOKEN=$(gh auth token)" >> .envand restart withnpm run stop && npm start(or add a provider in the portal's Admin Console). Then:npm run crawl -- --pilot # 10 threads in one session, to review first npm run crawl -- --concurrency 8 # then the rest, 8 sessions at a time npm run crawl -- --dedup # then one session that merges duplicates
Connect any MCP client to http://127.0.0.1:3102/mcp, or ask a pghacker Evaluator session in the portal. Answers cite Message-IDs, verbatim quotes, commit SHAs and file paths.
| Area | pghacker-mcp's tools |
|---|---|
search_threads, get_thread, search_extracts, author_perspective, search_authors, get_author |
|
| Code | search, grep, read_file, list_files and blame, at any commit; get_commit and search_commits, like git show and git log; search_patches, in the patches posted to the list |
| SQL and graph | get_ontology describes the data; query runs one read-only SQL statement, Cypher included |
It also serves a skill, review-as-author: a review of a patch, commit or design as a given pgsql-hackers author would give it (Tom Lane, say), each point quoting that author's own messages. Clients that support MCP's skills extension get it at skill://review-as-author/SKILL.md; the others get a tool, load_skill_review_as_author, which returns it, and instructions that say to call it. A user can also attach the skill as a resource, or install the folder as a skill in an agent; the reference explains.
npm test # the launcher, configuration, readiness and evaluation helpers
npm run rust:check # rustfmt, clippy and the Rust tests
npm run smoke # with the app running: both servers and their skills, the portal, the worker and the agents
npm run eval # with the data loaded (npm run load): 30 questions (eval/questions.json), into eval/RESULTS.md
npm run eval -- --questions eval/reviews.json --skill skills/review-as-author/SKILL.md --results eval/RESULTS-reviews.mdThe last reviews 14 patches as their actual reviewers would have (10 they objected to, 4 they welcomed), with the review-as-author skill in the prompt; without --skill, the agents must load it on their own, with load_skill_review_as_author.
deploy/README.md deploys the app to Azure Container Apps with Terraform, starting from the local corpus. There, the home page and /mcp are public, the portal, at /portal/ on Front Door's own host name, requires GitHub sign-in, and the indexer takes whatever sources its users ask for.
A deployment made with this repository's Terraform records usage telemetry in its own Application Insights: for each request to /mcp, the tool, its arguments' names and the shape of its answer (or the skill file read), the client, and an approximate location; and each view of the home page. What you type into tools, such as SQL and search terms, is recorded only if the deployment sets usage_details_enabled = true. The service's own logs, which go to the deployment's Log Analytics, keep a call's tool, duration and outcome and, for a failed query, PostgreSQL's error code and the first line of its message, with anything in double quotes elided; SQL and other arguments are logged only if RUST_LOG turns on debug logging. Now and then, as you start a new question in an interactive client such as GitHub Copilot, it also asks through the client's own form whether the last answer helped, and records your choice: the one thing pghacker-mcp writes, and only to telemetry, never to the data it serves. Your request runs whatever you choose. Add ?feedback=off to the MCP URL never to be asked. To turn feedback off, set feedback_rate_per_hour = 0, or to turn off all telemetry, usage_enabled = false, and run terraform apply. PRIVACY.md has the notice.
- Reference: settings, tools and their limits, the commit history, the graph, extraction, tests and the repository's layout.
- Design: why pghacker-mcp exists, and its plan.
- Search design: how the code tools read every commit.
- Deployment: Azure, upgrades and operations.
Tried it? We'd love to hear what worked, what didn't and what you'd like next: share your feedback, questions and ideas in Discussions. Report a bug in Issues, and a security vulnerability as SECURITY.md says.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
CONTRIBUTING.md explains how to build, check and propose a change, and SUPPORT.md how to get help.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Please do not report security vulnerabilities through public GitHub issues. To report one, follow SECURITY.md, which points to Microsoft's reporting guidance for its repositories at https://aka.ms/SECURITY.md.
MCP is a new and developing standard. As with all new technology standards, you should review the security of any systems that integrate with MCP servers, such as MCP hosts, clients, agents, AI applications, and models and confirm that they comply with system requirements, standards, and expectations. You should follow Microsoft security guidance for MCP servers, including enabling Entra ID authentication, secure token management, and network isolation. Refer to Microsoft Security Documentation for details.
This MCP server may provide access to underlying resources, such as tools, services, and/or data. Your use of that underlying resource via this MCP server is governed by the underlying resource's license terms.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
pghacker-mcp is licensed under the MIT License. NOTICE lists the third-party code in this repository and its license.