Skip to content
Skills Library
AI & agents · Tool integration

documentation-server

/documentation-server

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.

Licence
MIT
Last repository change
27.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
17
Deprecation

No signals detected. Repository changed on 27.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author 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.

How it works

  1. Overview
  2. When to Use
  3. Web Interface
  4. Server Lifecycle
  5. API Reference
  6. Example Usage
  7. Best Practices
  8. Common Mistakes
  9. Response Formats
Original SKILL.md headings · 244 lines, 1,272 words
SKILL.md preview
---
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

```bash
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)

```bash
# 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

```bash
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

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

### Add a document

```bash
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)

```bash
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

```bash
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

```bash
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:

```bash
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

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

### Process uploads folder

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

### List uploads

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

### Get uploads path

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

### Check server configuration

```bash
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)

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

Versions

The database has no other skills named documentation-server.

Database snapshot: 13.11.2026 · package version ccbd833095cc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90azure-ai
    Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe,…
  • 90azure-ai
    Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe,…
  • 100vectorize
    Runs semantic RAG and vector search over indexed knowledge via Vectorize MCP tools discovered at runtime. Use for memory retrieval, knowledge-base lookup, and evidence-backed answers from chunks.
  • 100rag-implementation
    Build Retrieval-Augmented Generation (RAG) systems for LLM applications with vector databases and semantic search. Use when implementing knowledge-grounded AI, building document Q&A systems, or int...
  • 100rag-implementation
    Build Retrieval-Augmented Generation (RAG) systems for LLM applications with vector databases and semantic search. Use when implementing knowledge-grounded AI, building document Q&A systems, or integrating LLMs with external knowledge bases.
  • 100rag-implementation
    Build Retrieval-Augmented Generation (RAG) systems for LLM applications with vector databases and semantic search. Use when implementing knowledge-grounded AI, building document Q&A systems, or integrating LLMs with external knowledge bases.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.