{
"markdown": "# NerdyGeek\n![\"NerdyGeek\"](\"https://github.com/user-attachments/assets/0ece259c-f69b-4084-af85-f850b6e2c219\")
\n\n> A docs-intelligence layer for coding agents.\n\n[](https://github.com/docxbox/NerdyGeek)\n[](https://modelcontextprotocol.io/)\n[](./LICENSE)\n[](https://github.com/docxbox/NerdyGeek/stargazers)\n\nNerdyGeek is an open-source TypeScript Node.js MCP server and Claude Code plugin that helps coding agents stop guessing from stale memory.\n\nWhen an agent gets stuck, NerdyGeek helps it:\n- fetch current official documentation\n- resolve version context from project files\n- compare framework upgrades\n- scan for deprecated or removed APIs\n- return compressed, source-backed answers instead of dumping long docs into context\n\nNerdyGeek is now successfully published in the Claude Code marketplace and also works with Codex and local MCP-based workflows.\n\n## Why NerdyGeek Exists\n\nCoding agents move fast, but documentation drift is real.\n\nThe moment version details matter, or a framework changes behavior, agents often:\n- guess from memory\n- pull noisy search results\n- use the wrong version of the docs\n- miss migration and deprecation details\n\nNerdyGeek exists to make agents behave more like careful engineers:\n- source-backed\n- version-aware\n- token-conscious\n- conservative when uncertain\n\n## Core Capabilities\n\nNerdyGeek currently exposes three MCP tools:\n\n- `search_docs`\n- `diff_docs`\n- `scan_deprecations`\n\n### `search_docs`\n\nVersion-aware official documentation lookup for frameworks, libraries, and APIs.\n\nUse it when an agent needs:\n- the latest official docs for a feature\n- docs pinned to the version in the repo\n- examples, gotchas, and source links\n\n### `diff_docs`\n\nStructured upgrade and migration comparison between versions.\n\nUse it when an agent needs:\n- breaking changes\n- removed APIs\n- deprecated APIs\n- migration guidance before an upgrade\n\n### `scan_deprecations`\n\nSource-code scan against official migration or deprecation docs.\n\nUse it when an agent needs:\n- outdated API detection\n- upgrade prep before a version bump\n- line-level findings for deprecated or removed usage\n\n## Shared Response Contract\n\nAll tools now return a shared agent-facing envelope:\n\n```ts\ntype NerdyGeekEnvelope = {\n tool: \"search_docs\" | \"diff_docs\" | \"scan_deprecations\";\n stack: string;\n version: string;\n mode: \"quick\" | \"full\" | \"deep\";\n summary: string;\n actions: string[];\n gotchas: string[];\n code?: string;\n sources: string[];\n confidence: number;\n docHandle: string;\n cacheStatus: \"hit\" | \"miss\";\n retrievedAt: string;\n};\n```\n\n![\"NerdyGeek](\"https://github.com/user-attachments/assets/78268d4b-4ecb-4075-a718-8db1821dfe45\")
\n\n![\"NerdyGeek](\"https://github.com/user-attachments/assets/a57a0ee4-a805-49c2-b916-992827487236\")
\n\nThis lets agents consume NerdyGeek results in a predictable, low-noise, token-efficient format.\n\n## What Makes NerdyGeek Different\n\nNerdyGeek uses a hybrid docs-intelligence approach:\n- dynamic discovery and ranking when that is reliable\n- curated authoritative fallbacks when ecosystems are noisy or ambiguous\n\nThat tradeoff gives you:\n- stronger official-source guarantees\n- better reliability in real coding sessions\n- fewer off-topic or SEO-polluted results\n- less philosophical purity than a zero-registry design, but much better practical outcomes\n\n## V4-Oriented Features\n\nNerdyGeek now includes a more infrastructure-style layer on top of its MCP tools:\n\n- shared response envelope across tools\n- persistent on-disk cache in `.nerdygeek/store.json`\n- reusable `docHandle` values for repeated lookups\n- cache hit/miss tracking\n- HTTP rate limiting for hosted mode\n- `/health`, `/ready`, and `/metrics` endpoints\n- structured logging\n\nIt is not the final word in production hardening yet, but it is well beyond a simple prototype plugin.\n\n## Install\n\n### Claude Code Marketplace\n\nNerdyGeek is published for Claude Code.\n\n```bash\nclaude plugin marketplace add docxbox/NerdyGeek\nclaude plugin install nerdygeek@nerdygeek\n```\n\nTo update later:\n\n```bash\nclaude plugin marketplace update nerdygeek\nclaude plugin update nerdygeek@nerdygeek\n```\n\n### Local Install\n\nClone the repo and build once:\n\n```bash\nnpm install\nnpm run build\n```\n\nThen install NerdyGeek for your coding agent:\n\n| Agent | Install |\n|---|---|\n| Claude Code | `npm run install:claude-code` |\n| Codex | `npm run install:codex` |\n| Both | `npm run install:all` |\n\n## Agent Setup\n\n### Claude Code\n\nRelevant files:\n\n- [`.mcp.json`](./.mcp.json)\n- [`.claude-plugin/plugin.json`](./.claude-plugin/plugin.json)\n- [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json)\n- [`skills/latest-docs/SKILL.md`](./skills/latest-docs/SKILL.md)\n\n### Codex\n\nNerdyGeek exposes an HTTP MCP endpoint for Codex:\n\n```toml\n[mcp_servers.nerdygeek]\nurl = \"http://127.0.0.1:3000/mcp\"\n```\n\nInstall helper:\n\n```bash\nnpm run install:codex\n```\n\nThen start the local MCP server:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\scripts\\start-codex-local.ps1\n```\n\nRelevant example configs:\n\n- [`examples/codex-config.toml`](./examples/codex-config.toml)\n- [`examples/codex-config.public.toml`](./examples/codex-config.public.toml)\n\n### Claude Desktop\n\nYou can also use the bundled Claude Desktop package:\n\n- [`artifacts/nerdygeek-1.0.0.mcpb`](./artifacts/nerdygeek-1.0.0.mcpb)\n- [`bundle/manifest.json`](./bundle/manifest.json)\n\n## Run Locally\n\nStdio MCP server:\n\n```bash\nnpm start\n```\n\nHTTP MCP server:\n\n```bash\nnpm run start:http\n```\n\nLocal HTTP endpoint:\n\n```text\nhttp://127.0.0.1:3000/mcp\n```\n\nOperational endpoints:\n\n```text\nhttp://127.0.0.1:3000/health\nhttp://127.0.0.1:3000/ready\nhttp://127.0.0.1:3000/metrics\n```\n\n## How It Works\n\nNerdyGeek follows a hybrid docs-intelligence pipeline:\n\n1. Detect the likely stack from the query and optional project metadata\n2. Resolve version context from the query, `package.json`, and supported lockfiles\n3. Discover official docs dynamically when possible\n4. Fall back to curated authoritative URLs when discovery is unreliable\n5. Retrieve relevant pages\n6. Extract clean text and code\n7. Rank chunks deterministically\n8. Format results into a shared agent envelope\n9. Persist by cache key and `docHandle`\n10. Validate before returning\n\nCore implementation:\n\n- [`src/searchDocs.ts`](./src/searchDocs.ts)\n- [`src/diffDocs.ts`](./src/diffDocs.ts)\n- [`src/scanDeprecations.ts`](./src/scanDeprecations.ts)\n- [`src/discovery.ts`](./src/discovery.ts)\n- [`src/formatter.ts`](./src/formatter.ts)\n- [`src/store.ts`](./src/store.ts)\n- [`src/metrics.ts`](./src/metrics.ts)\n- [`src/rateLimit.ts`](./src/rateLimit.ts)\n- [`src/retriever.ts`](./src/retriever.ts)\n- [`src/extractor.ts`](./src/extractor.ts)\n- [`src/ranker.ts`](./src/ranker.ts)\n- [`src/validation.ts`](./src/validation.ts)\n- [`src/mcpServer.ts`](./src/mcpServer.ts)\n- [`src/httpServer.ts`](./src/httpServer.ts)\n- [`src/stdio.ts`](./src/stdio.ts)\n\n## Scripts\n\n- `npm run build`\n- `npm start`\n- `npm run start:http`\n- `npm run bundle`\n- `npm run install:claude-code`\n- `npm run install:codex`\n- `npm run install:all`\n- `npm test`\n\n## Current Direction\n\nThe long-term vision is to make NerdyGeek feel less like a docs tool and more like a **NerdyGeek engineer**:\n- knows when to stop guessing\n- fetches the right docs before risky edits\n- preserves tokens through compression and cache reuse\n- stays aligned with the actual version in the repo\n- helps agents keep shipping without hallucinating\n\nThat is the standard this project is moving toward.\n\n## Star History\n\nIf NerdyGeek is useful, give it a star and help more agents stop coding from stale docs.\n\n[](https://www.star-history.com/#docxbox/NerdyGeek&Date)\n\n## License\n\n[MIT](./LICENSE)\n",
"bytes": 8176,
"sha": "60bced74b3f108629c7e21d799d901726956019dcb7d3c1d38712c64339354bf",
"repo_slug": "docxbox/nerdygeek",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_docxbox_nerdygeek_nerdygeek_e3d21527/readme"
}