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 "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

Mistake	Fix
Forgetting to start the server	Always check /api/config first; start if it fails
Not waiting for model download on first run	Use sleep 5 after starting; verify with the check step
Using wrong document ID	Always get the ID from list or search results first
Printing raw JSON in conversation	Log only what you need (IDs, scores, truncated snippets)
Expecting array from single-document GET	GET /api/documents/:id returns a single object, not an array
Putting the server on a different port	Default is 3080; override with WEB_PORT env var

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"}