documentation-server

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

Search

Uploads

Utility

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 "Content-Type: application/json" \
  -d '{"document_id": "DOCUMENT_ID_HERE", "parent_index": 3, "before": 2, "after": 2}'

Delete a document

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

Process uploads folder

curl -s -X POST http://127.0.0.1:3080/api/uploads/process

List uploads

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

Get uploads path

curl -s http://127.0.0.1:3080/api/uploads/path

Check server configuration

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

Returns server metadata: embedding model, Gemini availability, chunking settings.

AI-powered search (requires GEMINI_API_KEY)

curl -s -X POST http://127.0.0.1:3080/api/search-ai \
  -H "Content-Type: application/json" \
  -d '{"document_id": "DOCUMENT_ID_HERE", "query": "what does this document say about X?"}'

Returns an AI-generated answer grounded in the document content.

Best Practices

1. Always check if the server is running before making requests. Start it if inactive. A running server is safe to keep between sessions.

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.

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.

4. Handle the limit parameter. Default is 10. Increase for exhaustive searches, decrease for quick lookups.

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.

6. Document IDs are opaque strings (e.g. 4ecc2235ec887d3e). Always list documents first to get the correct ID.

7. First startup may be slow because the embedding model (~80 MB) is downloaded from Hugging Face. Subsequent starts are fast.

8. The server prints startup info to stdout. When started in background with > /tmp/doc-server.log, these logs don't clutter the terminal.

Common Mistakes

Response Formats

All endpoints return JSON. Typical response shapes:

• List documents: [{id, title, ...}]
• Single document: {id, title, content, metadata, createdAt}
• Add document: {success, id, title}
• Search results: [{content, score, document_id, parent_index, ...}]
• Context window: {parents: [{index, content, ...}], ...}
• Delete: {success, message}
• Error: {error: "message"}