Skip to content

Commit cabf886

Browse files
andrea9293andrea9293
authored
feat: add REST API skill for AI agents
feat: add REST API skill for AI agents
2 parents 6398932 + 48f2aa1 commit cabf886

2 files changed

Lines changed: 277 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,36 @@ npm run web:build # Production (compiled)
114114
2. Search across everything with `search_all_documents`, or within a single document with `search_documents`.
115115
3. Use `get_context_window` to fetch neighboring chunks and give the LLM broader context.
116116

117+
### 🤖 Agent Skill (REST API) — recommended for AI agents
118+
119+
Every MCP tool is also accessible via the **REST API** on `http://127.0.0.1:3080/api/`. **This is the recommended way to interact with the server from AI agents** (Claude Code, OpenCode, Gemini CLI, Cursor, etc.) because it avoids loading MCP tool schemas into the conversation context — only the response JSON enters.
120+
121+
```bash
122+
# Check if the server is running
123+
curl -s http://127.0.0.1:3080/api/config
124+
125+
# List all documents
126+
curl -s http://127.0.0.1:3080/api/documents
127+
128+
# Search across all documents
129+
curl -s -X POST http://127.0.0.1:3080/api/search-all \
130+
-H "Content-Type: application/json" \
131+
-d '{"query": "your search", "limit": 5}'
132+
```
133+
134+
A ready-to-use skill is included at `skills/documentation-server/SKILL.md` — it teaches your agent every endpoint with examples. Install it:
135+
136+
```bash
137+
# Install from the public repo
138+
npx skills add https://github.com/andrea9293/mcp-documentation-server --skill documentation-server
139+
```
140+
141+
Or manually:
142+
143+
```bash
144+
cp -r skills/documentation-server ~/.agents/skills/
145+
```
146+
117147
## MCP Tools
118148

119149
The server registers the following tools (all validated with Zod schemas):

‎skills/documentation-server/SKILL.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
---
2+
name: documentation-server
3+
description: Use when you need to store, retrieve, search, or manage documents in a local knowledge base with semantic search and hybrid (vector + full-text) retrieval. Also use when interacting with the documentation server web interface, managing uploads, or performing AI-powered document analysis. Use this instead of MCP-native tool definitions when context efficiency is a concern.
4+
---
5+
6+
# Documentation Server — REST API Skill
7+
8+
## Overview
9+
10+
This server provides a **local-first knowledge base** with semantic search, parent-child chunking, and an embedded vector database (Orama). Every operation available through the MCP protocol is also accessible via a **REST API** on `http://127.0.0.1:3080/api/`.
11+
12+
Calling the REST API directly (with `curl` or your agent's HTTP tool) is **more token-efficient** than loading MCP tool schemas — only the response JSON enters context, not the tool definitions.
13+
14+
## When to Use
15+
16+
- You need to add, retrieve, search, or delete documents in the knowledge base
17+
- You want **semantic search** (vector similarity) across one or all documents
18+
- You need to **retrieve context windows** around matched chunks for richer LLM context
19+
- You need to **manage uploads**: list files, process them into documents, or get the uploads path
20+
- You want the **web UI** to browse documents visually, upload files via drag-and-drop, or explore search results interactively
21+
- Context token budget is tight and you want to avoid MCP tool schema overhead
22+
23+
**When NOT to use**: If the server isn't running and you cannot start it (no `npx`/Node.js available), fall back to another documentation strategy.
24+
25+
## Web Interface
26+
27+
The server includes a full-featured **graphical web interface** at `http://127.0.0.1:3080` that runs automatically alongside the REST API. Use it for:
28+
29+
- **Dashboard** — overview of all documents and statistics
30+
- **Documents** — browse, view, and delete documents visually
31+
- **Add Document** — create documents with title, content, and metadata
32+
- **Search** — semantic search across all or within a specific document
33+
- **AI Search** — Gemini-powered analysis (if `GEMINI_API_KEY` is set)
34+
- **Upload Files** — drag-and-drop `.txt`, `.md`, or `.pdf` files
35+
- **Context Window** — explore chunks around a specific index interactively
36+
37+
The REST API is for programmatic access; the web UI is for visual exploration and one-off operations.
38+
39+
## Server Lifecycle
40+
41+
### 1. Check if the server is already running
42+
43+
```bash
44+
curl -s http://127.0.0.1:3080/api/config
45+
```
46+
47+
If you get a JSON response, the server is active. If the connection fails, proceed to start it.
48+
49+
### 2. Start the server (if inactive)
50+
51+
```bash
52+
# Start in background, redirect logs to a temp file
53+
npx -y @andrea9293/mcp-documentation-server > /tmp/doc-server.log 2>&1 &
54+
55+
# Wait for startup (embedding model download may take a few extra seconds on first run)
56+
sleep 5
57+
```
58+
59+
Then **verify** with the check step above. Retry after a few seconds if the model is still downloading.
60+
61+
### 3. Optional: stop the server
62+
63+
```bash
64+
pkill -f "@andrea9293/mcp-documentation-server" || true
65+
```
66+
67+
The server is safe to leave running in the background between sessions.
68+
69+
## API Reference
70+
71+
All endpoints are on `http://127.0.0.1:3080/api/`. All POST endpoints accept `Content-Type: application/json`.
72+
73+
### Document CRUD
74+
75+
| Method | Endpoint | Description |
76+
|--------|----------|-------------|
77+
| `GET` | `/api/documents` | List all documents |
78+
| `GET` | `/api/documents/:id` | Get a document's full content |
79+
| `POST` | `/api/documents` | Add a new document |
80+
| `DELETE` | `/api/documents/:id` | Delete a document |
81+
82+
### Search
83+
84+
| Method | Endpoint | Description |
85+
|--------|----------|-------------|
86+
| `POST` | `/api/search` | Semantic search within a single document |
87+
| `POST` | `/api/search-all` | Hybrid search across all documents |
88+
| `POST` | `/api/context-window` | Get surrounding chunks around a matched section |
89+
| `POST` | `/api/search-ai` | AI-powered analysis (requires `GEMINI_API_KEY`) |
90+
91+
### Uploads
92+
93+
| Method | Endpoint | Description |
94+
|--------|----------|-------------|
95+
| `GET` | `/api/uploads` | List files in the uploads folder |
96+
| `GET` | `/api/uploads/path` | Get the uploads directory path |
97+
| `POST` | `/api/uploads/process` | Process all pending upload files into documents |
98+
| `POST` | `/api/uploads/upload` | Upload files via multipart form |
99+
100+
### Utility
101+
102+
| Method | Endpoint | Description |
103+
|--------|----------|-------------|
104+
| `GET` | `/api/config` | Server configuration (embedding model, Gemini availability) |
105+
106+
## Example Usage
107+
108+
### List all documents
109+
110+
```bash
111+
curl -s http://127.0.0.1:3080/api/documents
112+
```
113+
114+
### Add a document
115+
116+
```bash
117+
curl -s -X POST http://127.0.0.1:3080/api/documents \
118+
-H "Content-Type: application/json" \
119+
-d '{
120+
"title": "My Document Title",
121+
"content": "Full document content here...",
122+
"metadata": { "source": "web", "tags": ["reference"] }
123+
}'
124+
```
125+
126+
### Search across all documents (hybrid search)
127+
128+
```bash
129+
curl -s -X POST http://127.0.0.1:3080/api/search-all \
130+
-H "Content-Type: application/json" \
131+
-d '{"query": "your search query here", "limit": 10}'
132+
```
133+
134+
Each result includes:
135+
- `content` — the matched text chunk
136+
- `score` — relevance score (0-1, higher = more relevant)
137+
- `document_id` — ID of the document this chunk belongs to
138+
- `parent_index` — chunk index within the document (needed for context window queries)
139+
140+
### Get a document's full content by ID
141+
142+
```bash
143+
curl -s http://127.0.0.1:3080/api/documents/DOCUMENT_ID_HERE
144+
```
145+
146+
Note: returns a **single object**, not an array.
147+
148+
### Search within a specific document
149+
150+
```bash
151+
curl -s -X POST http://127.0.0.1:3080/api/search \
152+
-H "Content-Type: application/json" \
153+
-d '{"document_id": "DOCUMENT_ID_HERE", "query": "search term", "limit": 5}'
154+
```
155+
156+
### Get context window around a chunk
157+
158+
After search results give you a `document_id` and `parent_index`, expand the context:
159+
160+
```bash
161+
curl -s -X POST http://127.0.0.1:3080/api/context-window \
162+
-H "Content-Type: application/json" \
163+
-d '{"document_id": "DOCUMENT_ID_HERE", "parent_index": 3, "before": 2, "after": 2}'
164+
```
165+
166+
### Delete a document
167+
168+
```bash
169+
curl -s -X DELETE http://127.0.0.1:3080/api/documents/DOCUMENT_ID_HERE
170+
```
171+
172+
### Process uploads folder
173+
174+
```bash
175+
curl -s -X POST http://127.0.0.1:3080/api/uploads/process
176+
```
177+
178+
### List uploads
179+
180+
```bash
181+
curl -s http://127.0.0.1:3080/api/uploads
182+
```
183+
184+
### Get uploads path
185+
186+
```bash
187+
curl -s http://127.0.0.1:3080/api/uploads/path
188+
```
189+
190+
### Check server configuration
191+
192+
```bash
193+
curl -s http://127.0.0.1:3080/api/config
194+
```
195+
196+
Returns server metadata: embedding model, Gemini availability, chunking settings.
197+
198+
### AI-powered search (requires GEMINI_API_KEY)
199+
200+
```bash
201+
curl -s -X POST http://127.0.0.1:3080/api/search-ai \
202+
-H "Content-Type: application/json" \
203+
-d '{"document_id": "DOCUMENT_ID_HERE", "query": "what does this document say about X?"}'
204+
```
205+
206+
Returns an AI-generated answer grounded in the document content.
207+
208+
## Best Practices
209+
210+
1. **Always check if the server is running before making requests.** Start it if inactive. A running server is safe to keep between sessions.
211+
212+
2. **Prefer calling the REST API over MCP tool definitions** — the REST API returns JSON directly without the overhead of loading tool schemas into the agent's context window.
213+
214+
3. **Keep output minimal.** For lists: just IDs and titles. For search: scores and truncated content snippets (~200 chars is usually enough). For errors: the error message.
215+
216+
4. **Handle the `limit` parameter.** Default is 10. Increase for exhaustive searches, decrease for quick lookups.
217+
218+
5. **Use the web UI** (`http://127.0.0.1:3080`) for visual browsing, drag-and-drop uploads, and one-off operations. The REST API is for programmatic access.
219+
220+
6. **Document IDs are opaque strings** (e.g. `4ecc2235ec887d3e`). Always list documents first to get the correct ID.
221+
222+
7. **First startup may be slow** because the embedding model (~80 MB) is downloaded from Hugging Face. Subsequent starts are fast.
223+
224+
8. **The server prints startup info to stdout.** When started in background with `> /tmp/doc-server.log`, these logs don't clutter the terminal.
225+
226+
## Common Mistakes
227+
228+
| Mistake | Fix |
229+
|---------|-----|
230+
| Forgetting to start the server | Always check `/api/config` first; start if it fails |
231+
| Not waiting for model download on first run | Use `sleep 5` after starting; verify with the check step |
232+
| Using wrong document ID | Always get the ID from `list` or `search` results first |
233+
| Printing raw JSON in conversation | Log only what you need (IDs, scores, truncated snippets) |
234+
| Expecting array from single-document GET | `GET /api/documents/:id` returns a **single object**, not an array |
235+
| Putting the server on a different port | Default is 3080; override with `WEB_PORT` env var |
236+
237+
## Response Formats
238+
239+
All endpoints return JSON. Typical response shapes:
240+
241+
- **List documents:** `[{id, title, ...}]`
242+
- **Single document:** `{id, title, content, metadata, createdAt}`
243+
- **Add document:** `{success, id, title}`
244+
- **Search results:** `[{content, score, document_id, parent_index, ...}]`
245+
- **Context window:** `{parents: [{index, content, ...}], ...}`
246+
- **Delete:** `{success, message}`
247+
- **Error:** `{error: "message"}`

0 commit comments

Comments
 (0)