### Install Project Dependencies

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Install all necessary Node.js dependencies for the project using npm.

```bash
npm install
```

--------------------------------

### Clone and Install Project Dependencies

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Clone the repository and install project dependencies using npm.

```bash
git clone https://github.com/andrea9293/mcp-documentation-server.git
cd mcp-documentation-server
npm install
```

--------------------------------

### Configure MCP Client (Basic)

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Example configuration for an MCP client to connect to the documentation server. This uses the default command and arguments.

```json
{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": [
        "-y",
        "@andrea9293/mcp-documentation-server"
      ]
    }
  }
}
```

--------------------------------

### Start Development Server with Hot Reload

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Starts the development server, which automatically rebuilds and reloads on code changes.

```bash
npm run dev
```

--------------------------------

### Run Direct Development Server

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Starts the development server directly, bypassing the FastMCP wrapper for specific testing scenarios.

```bash
npm run dev:direct
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

An example demonstrating how to use the Conventional Commits format for commit messages, including a breaking change.

```bash
feat: change document storage format

BREAKING CHANGE: Document storage format has changed. 
Existing documents need to be re-imported.
```

--------------------------------

### List all documents via REST API

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Use this `GET` request to retrieve a list of all documents managed by the server. The response includes metadata and a content preview for each document.

```bash
curl http://localhost:3080/api/documents

# Response: 200 OK
[
  {
    "id": "a3f9c1e2b4d67890",
    "title": "TypeScript Handbook",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z",
    "metadata": { "author": "Microsoft" },
    "content_preview": "## Introduction\nTypeScript is a typed superset...",
    "chunks_count": 42
  }
]
```

--------------------------------

### Add Document MCP Tool Call

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

This is an example of how to call the `add_document` MCP tool. Provide the document's title, full content, and optional metadata. The server will handle chunking, embedding, and persistence.

```json
// MCP tool call
{
  "tool": "add_document",
  "arguments": {
    "title": "TypeScript Handbook",
    "content": "## Introduction\nTypeScript is a typed superset of JavaScript...\n\n## Basic Types\nTypeScript supports `string`, `number`, `boolean`...",
    "metadata": {
      "author": "Microsoft",
      "tags": ["typescript", "programming"],
      "version": "5.0"
    }
  }
}
```

```json
// Response
"Document added successfully with ID: a3f9c1e2b4d67890"
```

--------------------------------

### Commit Changes with Conventional Commits

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Examples of using conventional commit messages for feature, fix, and documentation changes.

```bash
git commit -m "feat: add PDF text extraction support"
git commit -m "fix: resolve embedding model initialization error"
git commit -m "docs: update README with new features"
```

--------------------------------

### List Files in Uploads Folder

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Get a list of all files currently stored in the server's uploads folder. Includes file name, size, modification date, and supported status.

```bash
curl http://localhost:3080/api/uploads
```

--------------------------------

### Get a single document via REST API

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Use this `GET` request with a document ID to retrieve the full document object, including its chunks. Handles 'Document not found' errors.

```bash
curl http://localhost:3080/api/documents/a3f9c1e2b4d67890

# Response: 200 OK — full Document object with chunks array
# Response: 404 { "error": "Document not found: a3f9c1e2b4d67890" }
```

--------------------------------

### Create Feature or Fix Branch

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Branching strategy for starting new development work, whether for new features or bug fixes.

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description
```

--------------------------------

### Get Context Window for Chunk

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Fetches neighboring chunks around a given chunk index. This provides broader context for the LLM, improving understanding.

```python
get_context_window(id: str, chunk_index: int)
```

--------------------------------

### GET /api/documents

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Lists all documents stored in the system. Returns a summary of each document including its ID, title, creation and update timestamps, metadata, and a content preview.

```APIDOC
## GET /api/documents — List all documents

### Description
Lists all documents stored in the system. Returns a summary of each document including its ID, title, creation and update timestamps, metadata, and a content preview.

### Method
GET

### Endpoint
/api/documents

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the document.
- **title** (string) - The title of the document.
- **created_at** (string) - Timestamp when the document was created.
- **updated_at** (string) - Timestamp when the document was last updated.
- **metadata** (object) - Key-value pairs for additional document information.
- **content_preview** (string) - A short preview of the document's content.
- **chunks_count** (integer) - The number of text chunks the document is divided into.

### Request Example
```bash
curl http://localhost:3080/api/documents
```

### Response Example
```json
[
  {
    "id": "a3f9c1e2b4d67890",
    "title": "TypeScript Handbook",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z",
    "metadata": { "author": "Microsoft" },
    "content_preview": "## Introduction\nTypeScript is a typed superset...",
    "chunks_count": 42
  }
]
```
```

--------------------------------

### Get MCP Web UI URL

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Returns the URL for the Web UI, typically http://localhost:3080. This is helpful for accessing the dashboard or locating the uploads folder via the browser.

```python
get_ui_url()
```

--------------------------------

### Initialize Application Configuration

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/src/public/index.html

Fetches application configuration on startup and conditionally displays navigation elements based on Gemini availability.

```javascript
async function init() { try { config = await api('GET', '/config'); if (config.gemini_available) { document.getElementById('nav-search-ai').style.display = ''; } } catch (e) { console.error('Failed to load config', e); } await loadDashboard(); } init();
```

--------------------------------

### Clone Repository and Set Up Remotes

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Clone your forked repository and add the upstream remote to fetch changes from the original project.

```bash
git clone https://github.com/YOUR_USERNAME/mcp-documentation-server.git
cd mcp-documentation-server

git remote add upstream https://github.com/andrea9293/mcp-documentation-server.git
```

--------------------------------

### Build and Inspect Project Tools

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Commands to build the project and then inspect its functionality, typically via a web interface.

```bash
npm run build

npm run inspect
```

--------------------------------

### Get uploads directory path

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Retrieves the absolute path to the server's uploads directory.

```APIDOC
## GET /api/uploads/path — Get uploads directory path

### Description
Retrieves the absolute path to the server's uploads directory.

### Method
GET

### Endpoint
/api/uploads/path

### Response
#### Success Response (200 OK)
- **path** (string) - The absolute path to the uploads directory.

#### Response Example
```json
{ "path": "/home/user/.mcp-documentation-server/uploads" }
```
```

--------------------------------

### Get Document Title

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/src/public/index.html

Retrieves the title of a document given its ID. Returns the ID if the document is not found.

```javascript
function getDocTitle(id) { const doc = documents.find(d => d.id === id); return doc ? doc.title : id; }
```

--------------------------------

### Build and Run Project Commands

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Commands to build the project, run it in development mode with hot reload, and inspect its tools.

```bash
npm run build

npm run dev

npm run inspect
```

--------------------------------

### MCP Architecture Overview

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Provides a high-level overview of the server's architecture, detailing the components and their interactions, including the Web UI, MCP Tools, and DocumentManager.

```text
Server (FastMCP, stdio)
  ├─ Web UI (Express, port 3080)
  │    └─ REST API → DocumentManager
  └─ MCP Tools
       └─ DocumentManager
            ├─ OramaStore          — Orama vector DB (chunks DB + docs DB + parents DB), persistence, migration
            ├─ IntelligentChunker  — Parent-child chunking (code, markdown, text, PDF)
            ├─ EmbeddingProvider   — Local embeddings via @xenova/transformers
            │    └─ EmbeddingCache — LRU in-memory cache
            └─ GeminiSearchService — Optional AI search via Google Gemini

```

--------------------------------

### Run Development and Build Commands

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Execute various npm scripts for development, building, and testing the FastMCP server and web UI.

```bash
npm run dev       # FastMCP dev mode with hot reload
npm run build     # TypeScript compilation
npm run inspect   # FastMCP web UI for interactive tool testing
npm start         # Direct tsx execution (MCP server + web UI)
npm run web       # Run only the web UI (development)
npm run web:build # Run only the web UI (compiled)
```

--------------------------------

### Project Structure

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

An overview of the project's directory structure, highlighting key directories and files.

```text
src/
  server.ts              # Main MCP server implementation
  document-manager.ts    # Document storage and retrieval
  embedding-provider.ts  # AI embedding abstraction
  search-engine.ts       # Semantic search functionality
  types.ts              # TypeScript type definitions
  utils.ts              # Utility functions

.github/
  workflows/            # CI/CD workflows
  copilot-instructions.md

docs/
  README.md
  SECURITY.md
  CONTRIBUTING.md (this file)
```

--------------------------------

### GET /api/documents/:id

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Retrieves a single document by its ID. Returns the full document object, including its content and associated chunks.

```APIDOC
## GET /api/documents/:id — Get a single document

### Description
Retrieves a single document by its ID. Returns the full document object, including its content and associated chunks.

### Method
GET

### Endpoint
/api/documents/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the document to retrieve.

### Response
#### Success Response (200)
- Returns the full Document object with a chunks array.

#### Error Response (404)
- **error** (string) - Description of the error, e.g., "Document not found: [id]"

### Request Example
```bash
curl http://localhost:3080/api/documents/a3f9c1e2b4d67890
```
```

--------------------------------

### Get context window around a parent section

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Retrieves a context window of content surrounding a specified parent section within a document.

```APIDOC
## POST /api/context-window — Get context window around a parent section

### Description
Retrieves a context window of content surrounding a specified parent section within a document.

### Method
POST

### Endpoint
/api/context-window

### Parameters
#### Request Body
- **document_id** (string) - Required - The ID of the document.
- **parent_index** (integer) - Required - The index of the parent section.
- **before** (integer) - Optional - The number of sections to include before the parent section.
- **after** (integer) - Optional - The number of sections to include after the parent section.

### Request Example
```json
{
  "document_id": "a3f9c1e2b4d67890",
  "parent_index": 3,
  "before": 1,
  "after": 1
}
```

### Response
#### Success Response (200 OK)
- **window** (array) - An array of objects, each representing a section within the context window. Each object contains:
  - **parent_index** (integer) - The index of the section.
  - **content** (string) - The content of the section.
  - **heading** (string) - The heading of the section.
- **center** (integer) - The index of the central parent section.
- **total_parents** (integer) - The total number of parent sections in the document.

#### Response Example
```json
{
  "window": [
    { "parent_index": 2, "content": "## Basic Types\n...", "heading": "Basic Types" },
    { "parent_index": 3, "content": "## Interfaces\n...", "heading": "Interfaces" },
    { "parent_index": 4, "content": "## Type Aliases\n...", "heading": "Type Aliases" }
  ],
  "center": 3,
  "total_parents": 18
}
```
```

--------------------------------

### Response from `get_uploads_path` tool

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Provides the filesystem path to the uploads folder and suggests placing .txt and .md files there for subsequent processing.

```json
"Uploads folder path: /home/user/.mcp-documentation-server/uploads\n\nYou can place .txt and .md files in this folder, then use the 'process_uploads' tool to create embeddings for them."
```

--------------------------------

### Get Uploads Directory Path

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Retrieve the absolute path to the server's uploads directory. This can be useful for external file system operations.

```bash
curl http://localhost:3080/api/uploads/path
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Create a .env file to set environment variables for local development, such as the embedding model.

```bash
MCP_EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
```

--------------------------------

### Configure MCP Client for Documentation Server

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

This JSON configuration is used by MCP clients like Claude Desktop or VS Code to connect to the MCP Documentation Server. Ensure the 'command' and 'args' correctly point to the server executable and set environment variables for customization.

```json
{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@andrea9293/mcp-documentation-server"],
      "env": {
        "MCP_BASE_DIR": "/path/to/workspace",
        "GEMINI_API_KEY": "your-gemini-api-key",
        "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
        "START_WEB_UI": "true",
        "WEB_PORT": "3080",
        "MCP_CACHE_ENABLED": "true",
        "MCP_STREAMING_ENABLED": "true",
        "MCP_STREAM_FILE_SIZE_LIMIT": "10485760",
        "MCP_STREAM_CHUNK_SIZE": "65536"
      }
    }
  }
}
```

--------------------------------

### Get Document Content by ID

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Fetch the complete content of a specific document using its unique identifier. This is useful when you need the full text of a document.

```python
get_document(id: str)
```

--------------------------------

### Configure MCP Base Directory

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Set the base directory for data storage using the `MCP_BASE_DIR` environment variable. Defaults to `~/.mcp-documentation-server`.

```bash
export MCP_BASE_DIR="/path/to/custom/storage"
```

--------------------------------

### Server Configuration Info

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Retrieve information about the server's current configuration, including the availability of AI features and the embedding model being used.

```bash
curl http://localhost:3080/api/config
```

--------------------------------

### Get Uploads Folder Path

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Retrieves the absolute path to the server's uploads folder. Use this to programmatically access or manage files within the uploads directory.

```python
get_uploads_path()
```

--------------------------------

### Create Lazy and Eager Embedding Providers with Transformers

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Use `createLazyEmbeddingProvider` for non-blocking model loading on server startup. `createEmbeddingProvider` loads models eagerly and can fall back to a simpler provider. Both use `@xenova/transformers` for local model execution with caching.

```typescript
import {
  createLazyEmbeddingProvider,
  createEmbeddingProvider,
  TransformersEmbeddingProvider
} from './src/embedding-provider.js';

// Lazy (recommended for server startup — no blocking model load)
const lazyProvider = createLazyEmbeddingProvider('Xenova/all-MiniLM-L6-v2');
console.log(lazyProvider.getModelName());    // 'Xenova/all-MiniLM-L6-v2'
console.log(lazyProvider.getDimensions());   // 384

// Generate embedding (triggers model download on first call, ~80MB)
const embedding = await lazyProvider.generateEmbedding('How do I configure authentication?');
console.log(embedding.length); // 384 — normalized float32 vector

// Eager with fallback (tries models in order, falls back to SimpleEmbeddingProvider)
const eagerProvider = await createEmbeddingProvider('Xenova/paraphrase-multilingual-mpnet-base-v2');
const embedding768 = await eagerProvider.generateEmbedding('كيفية الاستيثاق');
console.log(embedding768.length); // 768

// Cache stats (when MCP_CACHE_ENABLED=true)
const stats = lazyProvider.getCacheStats();
// { size: 127, maxSize: 1000, hits: 843, misses: 127, hitRate: '86.9%' }
```

--------------------------------

### Add Document to MCP Server

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Use this tool to add a document with its title, content, and optional metadata. Ensure the document is properly formatted.

```python
add_document(title: str, content: str, metadata: Optional[Dict] = None)
```

--------------------------------

### Configure MCP Client (Advanced with Env Vars)

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Advanced configuration for an MCP client, including environment variables for customization. This allows setting base directories, API keys, embedding models, and web UI preferences.

```json
{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": [
        "-y",
        "@andrea9293/mcp-documentation-server"
      ],
      "env": {
        "MCP_BASE_DIR": "/path/to/workspace",
        "GEMINI_API_KEY": "your-api-key-here",
        "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
        "START_WEB_UI": "true",
        "WEB_PORT": "3080"
      }
    }
  }
}
```

--------------------------------

### Get Context Window Around a Parent Section

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Retrieve a context window of parent sections around a specified parent index within a document. Useful for understanding the surrounding content of a particular section.

```bash
curl -X POST http://localhost:3080/api/context-window \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "a3f9c1e2b4d67890",
    "parent_index": 3,
    "before": 1,
    "after": 1
  }'
```

--------------------------------

### Get Context Window Around Search Result

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Retrieves a sliding window of surrounding parent sections for a given `document_id` and `parent_index` from a search result. Use `before` and `after` parameters to control the number of neighboring sections included, providing broader context without loading the entire document.

```json
{ "tool": "get_context_window", "arguments": { "document_id": "a3f9c1e2b4d67890", "parent_index": 3, "before": 1, "after": 2 } }
```

```json
{
  "window": [
    { "parent_index": 2, "content": "## Basic Types\n...", "heading": "Basic Types" },
    { "parent_index": 3, "content": "## Interfaces\n...", "heading": "Interfaces" },
    { "parent_index": 4, "content": "## Type Aliases\n...", "heading": "Type Aliases" },
    { "parent_index": 5, "content": "## Union Types\n...", "heading": "Union Types" }
  ],
  "center": 3,
  "total_parents": 18
}
```

--------------------------------

### Ensure Build Passes

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Run the build script to verify that the project compiles successfully before submitting a pull request.

```bash
npm run build
```

--------------------------------

### Run Web UI Standalone

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Commands to run the web UI independently. Use 'npm run web' for development with live reloading and 'npm run web:build' for a production-ready compiled version.

```bash
npm run web

```

```bash
npm run web:build
```

--------------------------------

### Access Web UI

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

The web interface is accessible via localhost on the configured port, typically 3080. This URL allows direct access to the dashboard and tools.

```bash
http://localhost:3080
```

--------------------------------

### Response from `process_uploads` tool

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Returns a processing summary indicating completion status, number of files processed, and any errors encountered during processing.

```json
"Processing completed!\n- Files processed: 3\n"
```

```json
"Processing completed!\n- Files processed: 2\n- Errors encountered: 1\n\nErrors:\n  • Error processing report.pdf: No text found in PDF or PDF might be image-based"
```

--------------------------------

### MCP Storage Layout

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Illustrates the directory structure for data storage, including Orama databases, migration flags, and uploaded files.

```text
~/.mcp-documentation-server/     # Or custom path via MCP_BASE_DIR
├── data/
│   ├── orama-chunks.msp         # Orama vector DB (child chunks + embeddings)
│   ├── orama-docs.msp           # Orama document DB (full content + metadata)
│   ├── orama-parents.msp        # Orama parent chunks DB (context sections)
│   ├── migration-complete.flag   # Written after legacy JSON migration
│   └── *.md                     # Markdown copies of documents
└── uploads/                     # Drop .txt, .md, .pdf files here

```

--------------------------------

### Configure Web UI Port

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Change the port for the web UI using the `WEB_PORT` environment variable. The default is `3080`.

```bash
export WEB_PORT="8080"
```

--------------------------------

### Load Context Window API

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/src/public/index.html

Fetches context window data from the API and updates the UI. Handles loading states and errors.

```javascript
HTML = '<div style="text-align:center;padding:20px"><span class="spinner"></span> Loading...</div>'; try { const result = await api('POST', '/context-window', { document_id, parent_index, before, after }); const combinedText = result.window.map(c => c.content).join('\n\n'); container.innerHTML = 
`<div class="card"> 
 <div class="card-title">Context Window · Sections ${result.window[0].parent_index}–${result.window[result.window.length-1].parent_index} of ${result.total_parents - 1}</div> 
 <div class="chunk-nav"> ${result.window.map(c => 
 
 <span class="chunk-badge ${c.parent_index === result.center ? 'center' : ''}">#${c.parent_index}</span> 
 ).join('')} 
 </div> 
 <div class="doc-content-view" style="white-space:pre-wrap;line-height:1.7">${escHtml(combinedText)}</div> 
 </div>
`; } catch (err) { container.innerHTML = ''; toast(err.message, 'error'); }
```

--------------------------------

### Server configuration info

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Retrieves information about the server's current configuration, including AI model availability.

```APIDOC
## GET /api/config — Server configuration info

### Description
Retrieves information about the server's current configuration, including AI model availability.

### Method
GET

### Endpoint
/api/config

### Response
#### Success Response (200 OK)
- **gemini_available** (boolean) - Indicates whether the Gemini AI model is available for use.
- **embedding_model** (string) - The name of the embedding model currently in use by the server.

#### Response Example
```json
{
  "gemini_available": true,
  "embedding_model": "Xenova/all-MiniLM-L6-v2"
}
```
```

--------------------------------

### Context Shortcut from Search Results

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/src/public/index.html

Navigates to the context window view and pre-fills form fields based on search result data.

```javascript
function loadContext(docId, parentIdx) { navigateTo('context-window'); document.getElementById('cw-docid').value = docId; document.getElementById('cw-index').value = parentIdx; document.getElementById('context-form').dispatchEvent(new Event('submit')); }
```

--------------------------------

### List Documents in MCP Server

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Retrieve a list of all documents, including their metadata and a preview of their content. Useful for an overview of stored documents.

```python
list_documents()
```

--------------------------------

### Response from `get_ui_url` tool

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Provides the URL for accessing the web UI, typically used for browser-based file uploads or dashboard access.

```json
"Web UI URL: http://localhost:3080\n\nYou can access the web interface using this URL."
```

--------------------------------

### Response from `list_uploads_files` tool

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

The response is an array of objects, each detailing a file in the uploads directory, including its name, size, modification date, and processing support status.

```json
[
  {
    "name": "handbook.pdf",
    "size_bytes": 2048576,
    "modified": "2024-01-15T09:00:00.000Z",
    "supported": true,
    "status": "Can be processed"
  },
  {
    "name": "diagram.png",
    "size_bytes": 45678,
    "modified": "2024-01-14T12:00:00.000Z",
    "supported": false,
    "status": "Unsupported format"
  }
]
```

--------------------------------

### Call `search_documents_with_ai` tool

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Use this tool to perform AI-powered semantic search on documents. Requires `GEMINI_API_KEY` and uploads the document to Google Gemini Files API.

```json
{
  "tool": "search_documents_with_ai",
  "arguments": {
    "document_id": "a3f9c1e2b4d67890",
    "query": "generic constraints and conditional types"
  }
}
```

--------------------------------

### List Documents in Knowledge Base

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Retrieves all documents with their metadata, a content preview, and the count of child chunks. No parameters are required.

```json
{ "tool": "list_documents", "arguments": {} }
```

```json
[
  {
    "id": "a3f9c1e2b4d67890",
    "title": "TypeScript Handbook",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z",
    "metadata": { "author": "Microsoft", "tags": ["typescript"] },
    "content_preview": "## Introduction\nTypeScript is a typed superset of JavaScript...",
    "chunks_count": 42
  }
]
```

--------------------------------

### Call `list_uploads_files` tool

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Use this tool to inspect files in the uploads directory. It provides file names, sizes, modification timestamps, and support status for processing.

```json
{ "tool": "list_uploads_files", "arguments": {} }
```

--------------------------------

### Sync with Upstream

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Before submitting changes, ensure your local branch is up-to-date with the main branch of the upstream repository.

```bash
git fetch upstream
git rebase upstream/main
```

--------------------------------

### Disable Web UI

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Set `START_WEB_UI` to `false` to disable the built-in web interface. This is useful for headless operation.

```bash
export START_WEB_UI="false"
```

--------------------------------

### Process All Uploaded Files

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/src/public/index.html

Initiates the processing of all uploaded files via a POST request to the '/uploads/process' endpoint. It provides user feedback during processing and displays any errors encountered.

```javascript
async function processUploads() {
  const btn = event.target;
  btn.disabled = true;
  btn.innerHTML = '<span class="spinner"></span> Processing...';
  try {
    const result = await api('POST', '/uploads/process');
    toast(`Processed ${result.processed} files` + (result.errors.length ? ` with ${result.errors.length} errors` : ''), result.errors.length ? 'error' : 'success');
    if (result.errors.length) {
      result.errors.forEach(e => toast(e, 'error'));
    }
    refreshUploads();
    loadDashboard();
  } catch (e) {
    toast(e.message, 'error');
  } finally {
    btn.disabled = false;
    btn.innerHTML = '⚡ Process All';
  }
}
```

--------------------------------

### File Size Formatting Utility

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/src/public/index.html

Converts bytes into a human-readable format (B, KB, MB, GB). Returns '0 B' for zero bytes. Useful for displaying file sizes.

```javascript
function fmtSize(bytes) {
    if (bytes === 0) return '0 B';
    const sizes = ['B', 'KB', 'MB', 'GB'];
    const i = Math.floor(Math.log(bytes) / Math.log(1024));
    return (bytes / Math.pow(1024, i)).toFixed(1) + ' ' + sizes[i];
}
```

--------------------------------

### Call `get_ui_url` tool

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Returns the URL of the built-in web interface, recommended for users who wish to upload files via the browser or access the dashboard.

```json
{ "tool": "get_ui_url", "arguments": {} }
```

--------------------------------

### List Files in Uploads Folder

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Provides a list of files present in the uploads folder, including their size and format information. Useful for monitoring uploaded content.

```python
list_uploads_files()
```

--------------------------------

### process_uploads

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Batch processes files from the uploads folder. Scans for .txt, .md, and .pdf files, extracts text, chunks and embeds each file, and stores them as documents. Existing documents with the same title are replaced. Returns a processing summary.

```APIDOC
## `process_uploads` — Batch-process files from the uploads folder

### Description
Batch processes files from the uploads folder. Scans for `.txt`, `.md`, and `.pdf` files, extracts text (with PDF text extraction via `unpdf`), chunks and embeds each file, and stores them as documents. Existing documents with the same title are replaced. Returns a processing summary.

### Tool Call Example
```json
{ "tool": "process_uploads", "arguments": {} }
```

### Response Example (Success)
```
"Processing completed!\n- Files processed: 3\n"
```

### Response Example (With Errors)
```
"Processing completed!\n- Files processed: 2\n- Errors encountered: 1\n\nErrors:\n  • Error processing report.pdf: No text found in PDF or PDF might be image-based"
```
```

--------------------------------

### TypeScript Code Style Guidelines

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

Illustrates good and bad practices for TypeScript code, focusing on type safety, error handling, and interface usage.

```typescript
// ✅ Good
interface DocumentMetadata {
    source: string;
    processedAt: string;
    fileExtension: string;
}

async function processDocument(content: string): Promise<Document> {
    try {
        const chunks = await this.createChunks(content);
        return { /* ... */ };
    } catch (error) {
        throw new Error(`Failed to process document: ${error.message}`);
    }
}

// ❌ Avoid
function processDoc(content: any) {
    // No error handling, no types
    const chunks = this.createChunks(content);
    return chunks;
}
```

--------------------------------

### Load All Documents

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/src/public/index.html

Fetches all documents from the API and displays them in a table. Includes document title, ID, chunk count, and creation date. Call this function when the documents page is loaded.

```javascript
async function loadDocuments() {
    try {
        documents = await api('GET', '/documents');
        document.getElementById('doc-count-badge').textContent = documents.length;
        const tbody = document.getElementById('documents-table');
        const empty = document.getElementById('documents-empty');
        if (documents.length === 0) {
            tbody.innerHTML = '';
            empty.style.display = '';
            return;
        }
        empty.style.display = 'none';
        tbody.innerHTML = documents.map(d => ` <tr> <td><strong style="cursor:pointer;color:var(--accent)" onclick="viewDocument('${d.id}')">${escHtml(d.title)}</strong></td> <td class="id-cell">${d.id}</td> <td>${d.chunks_count}</td> <td>${fmtDate(d.created_at)}</td> <td> <div class="btn-group"> <button class="btn btn-secondary btn-sm" onclick="viewDocument('${d.id}')">👁 View</button> <button class="btn btn-danger btn-sm" onclick="confirmDelete('${d.id}', '${escHtml(d.title).replac
```

--------------------------------

### Add a new document via REST API

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Use this `POST` request to add a new document. Provide the title, content, and optional metadata in JSON format.

```bash
curl -X POST http://localhost:3080/api/documents \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Node.js Best Practices",
    "content": "## Error Handling\nAlways handle promise rejections...",
    "metadata": { "tags": ["nodejs", "backend"] }
  }'
```

--------------------------------

### Handle Context Window Form Submission

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/src/public/index.html

Listens for form submissions to retrieve contextual information for a given document ID and parent index. It sends the parameters to the backend and displays the results or an error.

```javascript
document.getElementById('context-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const document_id = document.getElementById('cw-docid').value;
  const parent_index = parseInt(document.getElementById('cw-index').value);
  const before = parseInt(document.getElementById('cw-before').value);
  const after = parseInt(document.getElementById('cw-after').value);
  const container = document.getElementById('context-results');
  container.inner
```

--------------------------------

### Enable Streaming Reads

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Enable streaming reads for large files by setting `MCP_STREAMING_ENABLED` to `true`. Defaults to `true`.

```bash
export MCP_STREAMING_ENABLED="true"
```

--------------------------------

### Configure Streaming File Size Limit

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/README.md

Set the threshold in bytes to switch to streaming using `MCP_STREAM_FILE_SIZE_LIMIT`. The default is 10485760 (10MB).

```bash
export MCP_STREAM_FILE_SIZE_LIMIT="20971520"
```

--------------------------------

### Bug Report Template

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

A markdown template for reporting bugs, including sections for bug description, reproduction steps, expected behavior, environment details, and additional context.

```markdown
**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Upload file type '...'
2. Run command '...'
3. See error

**Expected behavior**
What you expected to happen.

**Environment:**
- OS: [e.g. Windows 11, macOS 14, Ubuntu 22.04]
- Node.js version: [e.g. 22.0.0]
- Package version: [e.g. 1.4.0]

**Additional context**
Add any other context about the problem here.
```

--------------------------------

### Analyze Documents with GeminiSearchService

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Uploads documents to the Gemini Files API and uses `gemini-2.5-flash` for semantic analysis with a structured JSON output. Requires `GEMINI_API_KEY` and a `GeminiFileMappingService` to track uploaded files.

```typescript
import { GeminiSearchService } from './src/gemini-search-service.js';

// Requires GEMINI_API_KEY in environment or passed as last argument
const result = await GeminiSearchService.searchDocumentWithGemini(
  'c7a2e1f9b3d04567',          // document ID (must match a file in dataDir)
  'JWT token expiration policy',
  '/home/user/.mcp-documentation-server/data',
  process.env.GEMINI_API_KEY
);

const parsed = JSON.parse(result);
// {
//   search_results: "JWT tokens expire based on the `exp` claim...",
//   relevant_sections: [
//     { section_title: "Token Lifecycle", content: "...", relevance_score: 0.93, page_number: 4 }
//   ]
// }
```

--------------------------------

### Process All Files in Uploads Folder

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Initiate processing for all files currently located in the uploads folder. This endpoint triggers any necessary background tasks for uploaded files.

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

--------------------------------

### list_uploads_files

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Lists all files in the uploads directory, including their sizes, modification timestamps, and whether the format is supported for processing.

```APIDOC
## `list_uploads_files` — Inspect files in the uploads folder

### Description
Lists all files in the uploads directory, including their sizes, modification timestamps, and whether the format is supported for processing.

### Tool Call Example
```json
{ "tool": "list_uploads_files", "arguments": {} }
```

### Response Example
```json
[
  {
    "name": "handbook.pdf",
    "size_bytes": 2048576,
    "modified": "2024-01-15T09:00:00.000Z",
    "supported": true,
    "status": "Can be processed"
  },
  {
    "name": "diagram.png",
    "size_bytes": 45678,
    "modified": "2024-01-14T12:00:00.000Z",
    "supported": false,
    "status": "Unsupported format"
  }
]
```
```

--------------------------------

### Search All Documents Form Submission

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/src/public/index.html

Handles the submission of the 'search-all-form'. It retrieves the query and limit, displays a searching indicator, and makes a POST request to the '/search-all' endpoint. Renders results or an empty state message.

```javascript
document.getElementById('search-all-form').addEventListener('submit', async (e) => {
    e.preventDefault();
    const query = document.getElementById('sa-query').value.trim();
    const limit = parseInt(document.getElementById('sa-limit').value) || 10;
    const container = document.getElementById('search-all-results');
    container.innerHTML = '<div style="text-align:center;padding:20px"><span class="spinner"></span> Searching...</div>';
    try {
      const results = await api('POST', '/search-all', { query, limit });
      if (results.length === 0) {
        container.innerHTML = '<div class="empty-state"><div class="empty-state-icon">🔍</div><div class="empty-state-text">No results found</div></div>';
        return;
      }
      container.innerHTML = `<div class="card"><div class="card-title">Results (${results.length})</div>` + results.map((r, i) => ` <div class="result-item"> <div class="result-header"> <div class="result-meta">📄 <strong>${getDocTitle(r.document_id)}</strong> · Section #${r.parent_index}</div> <span class="result-score ${scoreClass(r.score)}">${(r.score * 100).toFixed(1)}%</span> </div> ${r.heading ? `<div class="result-heading">§ ${escHtml(r.heading)}</div>` : ''} <div class="result-content">${escHtml(r.content)}</div> <div style="margin-top:8px">
 <button class="btn btn-secondary btn-sm" onclick="loadContext('${r.document_id}', ${r.parent_index})">🪟 Context</button>
 </div> </div> `).join('') + '</div>';
    } catch (err) {
      container.innerHTML = '';
      toast(err.message, 'error');
    }
  });
```

--------------------------------

### Call `process_uploads` tool

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Use this tool to batch-process files from the uploads folder. It extracts text, chunks, embeds, and stores files as documents, replacing existing ones with the same title.

```json
{ "tool": "process_uploads", "arguments": {} }
```

--------------------------------

### Cross-Document Hybrid Search

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Execute a hybrid search across all documents using a query and an optional limit. This endpoint is useful for finding information across the entire documentation base.

```bash
curl -X POST http://localhost:3080/api/search-all \
  -H "Content-Type: application/json" \
  -d '{ "query": "dependency injection patterns", "limit": 10 }'
```

--------------------------------

### OramaStore: Initialize, Persist, and Retrieve Data

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

OramaStore manages Orama database instances for persisting and retrieving document chunks and parent sections. It supports vector/hybrid search and parent chunk lookups. Ensure vector dimensions match the embedding model.

```typescript
import { OramaStore } from './src/orama-store.js';

// vectorDimensions must match the embedding model (384 for MiniLM, 768 for mpnet)
const store = new OramaStore(384);
await store.initialize(); // restores from disk or creates fresh DBs

// Add a full document (after chunking)
await store.addDocument(document);            // persists chunks + doc metadata
await store.addParents(document.id, parents); // persists parent sections

// Retrieve
const doc = await store.getDocument('c7a2e1f9b3d04567');
const allDocs = await store.getAllDocuments();

// Vector + hybrid search
const queryEmbedding = await provider.generateEmbedding('authentication token');
// Search within one document (hybrid: full-text + vector)
const results = await store.searchChunks(queryEmbedding, 10, 'c7a2e1f9b3d04567', 'authentication token');
// Search across all documents (hybrid)
const allResults = await store.searchAllDocuments(queryEmbedding, 10, 'authentication token');

// Parent lookups for context window
const parent = await store.getParentChunk('c7a2e1f9b3d04567', 2);
const allParents = await store.getParentChunksForDocument('c7a2e1f9b3d04567');

// Delete (removes from all three DBs + persists)
const deleted = await store.deleteDocument('c7a2e1f9b3d04567'); // true
```

--------------------------------

### Feature Request Template

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/docs/CONTRIBUTING.md

A markdown template for submitting feature requests, including sections for the problem the feature addresses, the proposed solution, alternatives considered, and additional context.

```markdown
**Is your feature request related to a problem?**
A clear description of what the problem is.

**Describe the solution you'd like**
A clear description of what you want to happen.

**Describe alternatives you've considered**
Alternative solutions or features you've considered.

**Additional context**
Add any other context or screenshots about the feature request.
```

--------------------------------

### Handle Document Deletion Confirmation

Source: https://github.com/andrea9293/mcp-documentation-server/blob/main/src/public/index.html

Sets up an event listener for the 'confirm-yes-btn' to handle the deletion of a document via an API call. It reloads documents and the dashboard upon successful deletion.

```javascript
document.getElementById('confirm-yes-btn').addEventListener('click', async () => {
    if (!pendingDeleteId) return;
    try {
      await api('DELETE', '/documents/' + pendingDeleteId);
      toast('Document deleted', 'success');
      closeConfirm();
      loadDocuments();
      loadDashboard();
    } catch (e) {
      toast(e.message, 'error');
    }
  });
```

--------------------------------

### List files in the uploads folder

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Retrieves a list of all files currently present in the server's uploads folder.

```APIDOC
## GET /api/uploads — List files in the uploads folder

### Description
Retrieves a list of all files currently present in the server's uploads folder.

### Method
GET

### Endpoint
/api/uploads

### Response
#### Success Response (200 OK)
- Returns an array of file objects, each containing:
  - **name** (string) - The name of the file.
  - **size** (integer) - The size of the file in bytes.
  - **modified** (string) - The last modified date and time of the file (ISO 8601 format).
  - **supported** (boolean) - Indicates if the file type is supported by the server.

#### Response Example
```json
[
  { "name": "guide.md", "size": 12345, "modified": "2024-01-15T08:00:00.000Z", "supported": true },
  { "name": "notes.txt", "size": 4096, "modified": "2024-01-14T16:00:00.000Z", "supported": true }
]
```
```

--------------------------------

### Upload Files via Multipart Form

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Upload one or more files to the server's uploads folder using multipart form data. Supports uploading multiple files in a single request.

```bash
curl -X POST http://localhost:3080/api/uploads/upload \
  -F "files=@/path/to/guide.pdf" \
  -F "files=@/path/to/notes.md"
```

--------------------------------

### POST /api/documents

Source: https://context7.com/andrea9293/mcp-documentation-server/llms.txt

Adds a new document to the system. Requires a JSON payload with the document's title, content, and optional metadata.

```APIDOC
## POST /api/documents — Add a new document

### Description
Adds a new document to the system. Requires a JSON payload with the document's title, content, and optional metadata.

### Method
POST

### Endpoint
/api/documents

### Parameters
#### Request Body
- **title** (string) - Required - The title of the new document.
- **content** (string) - Required - The main content of the document.
- **metadata** (object) - Optional - Key-value pairs for additional document information.

### Request Example
```bash
curl -X POST http://localhost:3080/api/documents \
  -H "Content-Type: application/json" \
  -d '{ 
    "title": "Node.js Best Practices", 
    "content": "## Error Handling\nAlways handle promise rejections...", 
    "metadata": { "tags": ["nodejs", "backend"] }
  }'
```
```