EasyPeasyMCP

1# EasyPeasyMCP
2 
3<table><tr>
4<td><img src="assets/logo.png" alt="EasyPeasyMCP logo" /></td>
5<td>
6 
7A lightweight, zero-config [MCP](https://modelcontextprotocol.io/) server for documentation projects.
8 
9Give it an `llms-full.txt` file (local path or URL) and optional OpenAPI/AsyncAPI directories. It also hellps you to build one if you do not have it. It registers only the MCP tools that make sense for what you've provided — no code changes, no hard-coded paths.
10 
11</td>
12</tr></table>
13 
14<video src="https://github.com/user-attachments/assets/c4c20cfb-eba9-467f-9cdc-24e78e230b63" controls width="800"></video>
15 
16## Table of Contents
17 
18- [Why it's different](#why-its-different)
19- [When to use this — and when not to](#when-to-use-this--and-when-not-to)
20- [How it works](#how-it-works)
21- [Quick start](#quick-start)
22- [Generating llms-full.txt](#generating-llms-fulltxt)
23- [Configuration reference](#configuration-reference)
24  - [`easy-peasy-mcp` (MCP server)](#easy-peasy-mcp-mcp-server)
25  - [`easy-peasy-build` (llms-full.txt generator)](#easy-peasy-build-llms-fulltxt-generator)
26- [Local debugging](#local-debugging)
27 
28## Why it's different
29 
30* **No RAG, no vector database, no embedding pipeline.**
31Search is a case-insensitive line scan with configurable context — all in-process, in memory. For small projects with well-structured content like `llms-full.txt`, this is all you need to get started — no infrastructure, no ops burden, easy to pitch internally. The entire search capability is ~25 lines of vanilla JS with zero runtime dependencies.
32* **Any project with an `llms-full.txt` is MCP-enabled in 30 seconds.**
33Point `llmsTxt` at a hosted URL and you're done — no local file sync, no pipeline. Docs update, the AI gets fresh content automatically. It's the adoption curve that matters: the [llms.txt standard](https://llmstxt.org/) is becoming the norm for docs sites, and this tool makes every one of them instantly AI-accessible. 
34 
35    Don't have an `llms-full.txt` yet? No problem — as long as you have Markdown files, the bundled `easy-peasy-build` CLI will generate one for you from your docs and specs.
36* **Conditional tool registration keeps the AI's context clean.**
37No OpenAPI directory? No `list_openapi_specs` tool. Tools only appear when the content exists — the MCP surface matches exactly what you've provided.
38 
39## When to use this — and when not to
40 
41This is a **speed-first tool**. Use it when you need an agent to access new knowledge in minutes, not days — a quick proof of concept, a personal workflow, a demo, or an early internal pilot where getting something working fast matters more than getting it perfect.
42 
43For professional, long-term setups shared across teams, you will eventually want a proper **chunk → embed → RAG** pipeline instead. That gives you semantic search (the agent finds *meaning*, not just matching words), much lower token consumption per query, and the ability to scale across large or frequently updated knowledge bases without loading everything into memory. This tool loads the full content on every startup — that's fine for a few hundred KB, but it's a ceiling, not a foundation.
44 
45No docs at all? Not even Markdown files? If you're in a real hurry, just ask the agent to scrape the developer portal you depend on — it can crawl the relevant pages and pull the content together. It can even check common locations for OpenAPI or AsyncAPI specs and fetch those too. Combine that with `easy-peasy-build` and you have a working MCP server in minutes, with zero local files to maintain.
46 
47The honest summary: use this to validate that AI-assisted documentation is worth investing in. Once it is, graduate to a proper RAG stack.
48 
49## How it works
50 
51| What you provide | Tools registered |
52|---|---|
53| `llms-full.txt` | `get_full_documentation`, `search_documentation` |
54| OpenAPI directory | `list_openapi_specs`, `get_openapi_spec` |
55| AsyncAPI directory | `list_asyncapi_specs`, `get_asyncapi_spec` |
56 
57`search_documentation` covers all loaded content (llms-full.txt + all specs).
58 
59## Quick start
60 
61<table>
62<tr>
63<th>Option A — Config file</th>
64<th>Option B — CLI args</th>
65</tr>
66<tr>
67<td>
68 
69Drop an `.easypeasymcp.json` (or `.easypeasymcp.yaml`) in your docs project root:
70 
71**JSON:**
72```json
73{
74  "name": "my-project",
75  "llmsTxt": "./llms-full.txt",
76  "openapi": "./openapi",
77  "asyncapi": "./asyncapi",
78  "build": {
79    "docs": ["./guides", "./api-reference"]
80  }
81}
82```
83 
84**YAML:**
85```yaml
86name: my-project
87llmsTxt: ./llms-full.txt
88openapi: ./openapi
89asyncapi: ./asyncapi
90build:
91  docs:
92    - ./guides
93    - ./api-reference
94```
95 
96Paths are relative to the config file. Omit any key you don't have.
97`llmsTxt` can also be a URL. The `build` section is optional — include it if you want the server to regenerate `llms-full.txt` on every startup (add `--rebuild` to the command below).
98 
99**Registration requires absolute path to config file** (paths inside the config are relative to it):
100 
101```bash
102# Use absolute path
103claude mcp add my-project npx easy-peasy-mcp@0.0.11 \
104  -- --rebuild --config /absolute/path/to/.easypeasymcp.json
105 
106# Or convert relative to absolute with shell expansion
107claude mcp add my-project npx easy-peasy-mcp@0.0.11 \
108  -- --rebuild --config $(pwd)/.easypeasymcp.json
109```
110 
111</td>
112<td>
113 
114No config file needed — pass everything directly. Works with URLs too:
115 
116```bash
117claude mcp add asyncapi npx easy-peasy-mcp@0.0.11 -- \
118  --name "asyncapi" \
119  --llms https://raw.githubusercontent.com/derberg/EasyPeasyMCP/refs/heads/main/example-llms/asyncapi.txt
120```
121 
122</td>
123</tr>
124</table>
125 
126## Generating llms-full.txt
127 
128<table>
129<tr>
130<th width="30%">Option A — gitingest.com</th>
131<th width="70%">Option B — easy-peasy-build</th>
132</tr>
133<tr>
134<td>
135 
136[gitingest.com](https://gitingest.com/) generates a single combined text file from any public repo or website. Good for a one-off grab when you don't need the file to stay in sync with updates.
137 
138</td>
139<td>
140 
141For local Markdown files + OpenAPI/AsyncAPI specs:
142 
143```bash
144npx --package=easy-peasy-mcp@0.0.11 easy-peasy-build \
145  --docs ./guides \
146  --docs ./api-reference \
147  --openapi ./openapi \
148  --asyncapi ./asyncapi \
149  --output ./llms-full.txt
150```
151 
152- `--docs` is repeatable for multiple source directories
153- Reads `.md` and `.mdx` files recursively, sorted by name
154- OpenAPI/AsyncAPI files are included as code-fenced blocks
155- Omit `--output` to print to stdout
156 
157To keep `llms-full.txt` fresh automatically, add a `build` section to `.easypeasymcp.json` and pass `--rebuild` when registering the MCP server — it will regenerate on every startup instead of needing a manual run.
158 
159</td>
160</tr>
161</table>
162 
163## Configuration reference
164 
165### `easy-peasy-mcp` (MCP server)
166 
167| CLI flag | Config key | Description |
168|---|---|---|
169| `--config <path>` | — | Path to `.easypeasymcp.json`. Config file keys are used as defaults; CLI flags override them. |
170| `--name <string>` | `name` | Server name, shown in MCP client and embedded in tool descriptions. Defaults to `"docs"`. |
171| `--llms <path\|url>` | `llmsTxt` | Path or URL to `llms-full.txt`. Registers `get_full_documentation` and `search_documentation`. |
172| `--openapi <dir>` | `openapi` | Path to a directory of OpenAPI specs (JSON/YAML). Registers `list_openapi_specs` and `get_openapi_spec`. |
173| `--asyncapi <dir>` | `asyncapi` | Path to a directory of AsyncAPI specs (JSON/YAML). Registers `list_asyncapi_specs` and `get_asyncapi_spec`. |
174| `--rebuild` | `build` | Rebuild `llms-full.txt` from local sources on every startup. Requires a config file with a `build` section (see below). |
175| `--debug` | — | Enable debug logging to stderr. Useful for troubleshooting search issues or verifying content is loaded correctly. |
176 
177Config file paths are resolved relative to the config file's location. At least one of `--llms`, `--openapi`, or `--asyncapi` is required.
178 
179#### `build` config section
180 
181Optional. When present, add `--rebuild` to the `claude mcp add` command and the server will regenerate `llms-full.txt` on every startup.
182 
183```json
184{
185  "name": "my-project",
186  "llmsTxt": "./llms-full.txt",
187  "openapi": "./openapi",
188  "build": {
189    "docs": ["./guides", "./api-reference"],
190    "title": "My Project"
191  }
192}
193```
194 
195`openapi` and `asyncapi` from the top level are reused automatically. `llmsTxt` is the output path.
196 
197### `easy-peasy-build` (llms-full.txt generator)
198 
199| CLI flag | Description |
200|---|---|
201| `--docs <dir>` | Markdown source directory. Repeatable for multiple directories. |
202| `--openapi <dir>` | OpenAPI spec directory. Files included as code-fenced blocks. |
203| `--asyncapi <dir>` | AsyncAPI spec directory. Files included as code-fenced blocks. |
204| `--title <string>` | Project title for the generated file header. |
205| `--output <path>` | Output file path. Omit to print to stdout. |
206 
207## Local debugging
208 
209Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to interactively test the server:
210 
211<table>
212<tr>
213<th>With config file</th>
214<th>With CLI args</th>
215</tr>
216<tr>
217<td>
218 
219```bash
220npx @modelcontextprotocol/inspector@0.21.1 \
221  npx easy-peasy-mcp@0.0.11 -- \
222  --config /path/to/.easypeasymcp.json
223```
224 
225</td>
226<td>
227 
228```bash
229npx @modelcontextprotocol/inspector@0.21.1 \
230  npx easy-peasy-mcp@0.0.11 -- \
231  --llms /path/to/llms-full.txt \
232  --openapi /path/to/openapi
233```
234 
235</td>
236</tr>
237</table>
238 
239To try it right now without any local files:
240 
241```bash
242npx @modelcontextprotocol/inspector@0.21.1 \
243  npx easy-peasy-mcp@0.0.11 -- \
244  --llms https://raw.githubusercontent.com/derberg/EasyPeasyMCP/refs/heads/main/example-llms/asyncapi.txt
245```
246 
247**Tip:** Add `--debug` to see detailed logging about content loading and search operations:
248 
249```bash
250npx @modelcontextprotocol/inspector@0.21.1 \
251  npx easy-peasy-mcp@0.0.11 -- \
252  --config /path/to/.easypeasymcp.json \
253  --debug
254```
255 
256Debug logs appear in the **Server Notifications** view in the MCP Inspector UI.
257 
258