/documentation-server

name: documentation-server
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.

Documentation Server — REST API Skill

Overview

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/`.

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.

When to Use

• You need to add, retrieve, search, or delete documents in the knowledge base
• You want **semantic search** (vector similarity) across one or all documents
• You need to **retrieve context windows** around matched chunks for richer LLM context
• You need to **manage uploads**: list files, process them into documents, or get the uploads path
• You want the **web UI** to browse documents visually, upload files via drag-and-drop, or explore search results interactively
• Context token budget is tight and you want to avoid MCP tool schema overhead

**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.

Web Interface

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:

• **Dashboard** — overview of all documents and statistics
• **Documents** — browse, view, and delete documents visually
• **Add Document** — create documents with title, content, and metadata
• **Search** — semantic search across all or within a specific document
• **AI Search** — Gemini-powered analysis (if `GEMINI_API_KEY` is set)
• **Upload Files** — drag-and-drop `.txt`, `.md`, or `.pdf` files
• **Context Window** — explore chunks around a specific index interactively

The REST API is for programmatic access; the web UI is for visual exploration and one-off operations.

Server Lifecycle

1. Check if the server is already running

curl -s http://127.0.0.1:3080/api/config

If you get a JSON response, the server is active. If the connection fails, proceed to start it.

2. Start the server (if inactive)

# Start in background, redirect logs to a temp file
npx -y @andrea9293/mcp-documentation-server > /tmp/doc-server.log 2>&1 &

# Wait for startup (embedding model download may take a few extra seconds on first run)
sleep 5

Then **verify** with the check step above. Retry after a few seconds if the model is still downloading.

3. Optional: stop the server

pkill -f "@andrea9293/mcp-documentation-server" || true

The server is safe to leave running in the background between sessions.

API Reference

All endpoints are on `http://127.0.0.1:3080/api/`. All POST endpoints accept `Content-Type: application/json`.

Document CRUD

| Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/api/documents` | List all documents | | `GET` | `/api/documents/:id` | Get a document's full content | | `POST` | `/api/documents` | Add a new document | | `DELETE` | `/api/documents/:id` | Delete a document |

Search

| Method | Endpoint | Description | |--------|----------|-------------| | `POST` | `/api/search` | Semantic search within a single document | | `POST` | `/api/search-all` | Hybrid search across all documents | | `POST` | `/api/context-window` | Get surrounding chunks around a matched section | | `POST` | `/api/search-ai` | AI-powered analysis (requires `GEMINI_API_KEY`) |

Uploads

| Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/api/uploads` | List files in the uploads folder | | `GET` | `/api/uploads/path` | Get the uploads directory path | | `POST` | `/api/uploads/process` | Process all pending upload files into documents | | `POST` | `/api/uploads/upload` | Upload files via multipart form |

Utility

| Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/api/config` | Server configuration (embedding model, Gemini availability) |

Example Usage

List all documents

curl -s http://127.0.0.1:3080/api/documents

Add a document

curl -s -X POST http://127.0.0.1:3080/api/documents \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Document Title",
    "content": "Full document content here...",
    "metadata": { "source": "web", "tags": ["reference"] }
  }'

Search across all documents (hybrid search)

curl -s -X POST http://127.0.0.1:3080/api/search-all \
  -H "Content-Type: application/json" \
  -d '{"query": "your search query here", "limit": 10}'

Each result includes:

• `content` — the matched text chunk
• `score` — relevance score (0-1, higher = more relevant)
• `document_id` — ID of the document this chunk belongs to
• `parent_index` — chunk index within the document (needed for context window queries)

Get a document's full content by ID

curl -s http://127.0.0.1:3080/api/documents/DOCUMENT_ID_HERE

Note: returns a **single object**, not an array.

Search within a specific document

curl -s -X POST http://127.0.0.1:3080/api/search \
  -H "Content-Type: application/json" \
  -d '{"document_id": "DOCUMENT_ID_HERE", "query": "search term", "limit": 5}'

Get context window around a chunk

After search results give you a `document_id` and `parent_index`, expand the context:

curl -s -X POST http://127.0.0.1:3080/api/context-window \
  -H "Co