@arabold/docs-mcp-server 1.11.0 → 1.12.1

package/README.md

@@ -29,6 +29,7 @@ LLM-assisted coding promises speed and efficiency, but often falls short due to:
 - **Up-to-Date Knowledge:** Fetches the latest documentation directly from the source.
 - **Version-Aware Search:** Get answers relevant to specific library versions (e.g., `react@18.2.0` vs `react@17.0.0`).
 - **Accurate Snippets:** Reduces AI hallucinations by using context from official docs.
+- **Web Interface:** Provides a easy-to-use web interface for searching and managing documentation.
 - **Broad Source Compatibility:** Scrapes websites, GitHub repos, package manager sites (npm, PyPI), and even local file directories.
 - **Intelligent Processing:** Automatically chunks documentation semantically and generates embeddings.
 - **Flexible Embedding Models:** Supports OpenAI (incl. compatible APIs like Ollama), Google Gemini/Vertex AI, Azure OpenAI, AWS Bedrock, and more.
@@ -42,6 +43,10 @@ LLM-assisted coding promises speed and efficiency, but often falls short due to:
 
 Get up and running quickly!
 
+- [Option 1: Using Docker](#option-1-using-docker)
+- [Option 2: Using npx](#option-2-using-npx)
+- [Option 3: Using Docker Compose](#option-3-using-docker-compose)
+
 ### Option 1: Using Docker
 
 This approach is easy, straightforward, and doesn't require Node.js to be installed.
@@ -145,7 +150,7 @@ docker run -i --rm \
 
 ### Option 2: Using npx
 
-This approach is useful when you need local file access (e.g., indexing documentation from your local file system). While this can also be achieved by mounting paths into a Docker container, using npx is simpler but requires a Node.js installation.
+This approach is useful when you need local file access (e.g., indexing documentation from your local file system). While this can also be achieved by mounting paths into a Docker container, using `npx` is simpler but requires a Node.js installation.
 
 1. **Ensure Node.js is installed.**
 2. **Configure your MCP settings:**
@@ -173,22 +178,97 @@ This approach is useful when you need local file access (e.g., indexing document
 
 3. **That's it!** The server will now be available to your AI assistant.
 
-### Option 3: Using npx with HTTP Protocol
+### Option 3: Using Docker Compose
 
-Similar to Option 2, this uses `npx` to run the latest published package without needing Docker or a local clone. However, this option starts the server using the Streamable HTTP protocol instead of the default stdio, making it accessible via HTTP endpoints. This is useful if you have multiple clients, you work with multiple code assistants in parallel, or want to expose the server to other applications.
+This method provides a persistent local setup by running the server and web interface using Docker Compose. It requires cloning the repository but simplifies managing both services together.
 
-1.  **Ensure Node.js is installed.**
-2.  **Run the command:**
+1.  **Ensure Docker and Docker Compose are installed and running.**
+2.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/arabold/docs-mcp-server.git
+    cd docs-mcp-server
+    ```
+3.  **Set up your environment:**
+    Copy the example environment file and **edit it** to add your necessary API keys (e.g., `OPENAI_API_KEY`).
+    ```bash
+    cp .env.example .env
+    # Now, edit the .env file with your editor
+    ```
+    Refer to the [Configuration](#configuration) section for details on available environment variables.
+4.  **Launch the services:**
+    Run this command from the repository's root directory. It will build the images (if necessary) and start the server and web interface in the background.
 
     ```bash
-    # Ensure required environment variables like OPENAI_API_KEY are set
-    npx --package=@arabold/docs-mcp-server docs-server --protocol http --port 8000
+    docker compose up -d
     ```
 
-    - `--protocol http`: Instructs the server to use the HTTP protocol.
-    - `--port <number>`: Specifies the listening port (default: 8000).
+    - `-d`: Runs the containers in detached mode (in the background). Omit this to see logs directly in your terminal.
+
+    **Note:** If you pull updates for the repository (e.g., using `git pull`), you'll need to rebuild the Docker images to include the changes by running `docker compose up -d --build`.
+
+5.  **Configure your MCP client:**
+    Add the following configuration block to your MCP settings file (e.g., for Claude, Cline, Roo):
+
+    ```json
+    {
+      "mcpServers": {
+        "docs-mcp-server": {
+          "url": "http://localhost:6280/sse", // Connects via HTTP to the Docker Compose service
+          "disabled": false,
+          "autoApprove": []
+        }
+      }
+    }
+    ```
+
+    Restart your AI assistant application after updating the configuration.
+
+6.  **Access the Web Interface:**
+    The web interface will be available at `http://localhost:6281`.
+
+**Benefits of this method:**
+
+- Runs both the server and web UI with a single command.
+- Uses the local source code (rebuilds automatically if code changes and you run `docker compose up --build`).
+- Persistent data storage via the `docs-mcp-data` Docker volume.
+- Easy configuration management via the `.env` file.
+
+To stop the services, run `docker compose down` from the repository directory.
+
+## Using the Web Interface
+
+You can access a web-based GUI at `http://localhost:6281` to manage and search library documentation through your browser. **Important: Use the same method (Docker or npx) for both the server and web interface to ensure access to the same indexed documentation.**
+
+### Using Docker Web Interface
+
+If you're running the server with Docker, use Docker for the web interface as well:
+
+```bash
+docker run --rm \
+  -e OPENAI_API_KEY="your-openai-api-key-here" \
+  -v docs-mcp-data:/data \
+  -p 3000:3000 \
+  ghcr.io/arabold/docs-mcp-server:latest \
+  docs-web
+```
+
+Make sure to:
+
+- Use the same volume name (`docs-mcp-data` in this example) as your server
+- Map port 6281 with `-p 6281:3000`
+- Pass any configuration environment variables with `-e` flags
+
+### Using `npx Web Interface
+
+If you're running the server with `npx`, use `npx` for the web interface as well:
+
+```bash
+npx -y --package=@arabold/docs-mcp-server docs-web --port 6281
+```
+
+You can specify a different port using the `--port` flag.
 
-    The server will expose endpoints like `/mcp` and `/sse` on the specified port.
+The `npx` approach will use the default data directory on your system (typically in your home directory), ensuring consistency between server and web interface.
 
 ## Using the CLI
 
@@ -210,15 +290,15 @@ docker run --rm \
 
 Make sure to use the same volume name (`docs-mcp-data` in this example) as you did for the server. Any of the configuration environment variables (see [Configuration](#configuration) above) can be passed using `-e` flags, just like with the server.
 
-### Using npx CLI
+### Using `npx CLI
 
-If you're running the server with npx, use npx for the CLI as well:
+If you're running the server with npx, use `npx` for the CLI as well:
 
 ```bash
 npx -y --package=@arabold/docs-mcp-server docs-cli <command> [options]
 ```
 
-The npx approach will use the default data directory on your system (typically in your home directory), ensuring consistency between server and CLI.
+The `npx` approach will use the default data directory on your system (typically in your home directory), ensuring consistency between server and CLI.
 
 The main commands available are:
 

package/db/migrations/000-initial-schema.sql

@@ -0,0 +1,57 @@
+-- Initial database schema setup
+
+-- Documents table
+CREATE TABLE IF NOT EXISTS documents(
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  library TEXT NOT NULL,
+  version TEXT NOT NULL DEFAULT '',
+  url TEXT NOT NULL,
+  content TEXT,
+  metadata JSON,
+  sort_order INTEGER NOT NULL,
+  UNIQUE(url, library, version, sort_order)
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_documents_library_lower ON documents(lower(library));
+CREATE INDEX IF NOT EXISTS idx_documents_version_lower ON documents(lower(library), lower(version));
+
+-- Create Embeddings virtual table
+-- Note: Dimension is hardcoded here based on the value in schema.ts at the time of creation.
+-- If VECTOR_DIMENSION changes, a separate migration would be needed to update/recreate this table.
+CREATE VIRTUAL TABLE IF NOT EXISTS documents_vec USING vec0(
+  library TEXT NOT NULL,
+  version TEXT NOT NULL,
+  embedding FLOAT[1536]
+);
+
+-- Create FTS5 virtual table
+CREATE VIRTUAL TABLE IF NOT EXISTS documents_fts USING fts5(
+  content,
+  title,
+  url,
+  path,
+  tokenize='porter unicode61',
+  content='documents',
+  content_rowid='id'
+);
+
+-- Delete trigger to maintain FTS index
+CREATE TRIGGER IF NOT EXISTS documents_fts_after_delete AFTER DELETE ON documents BEGIN
+  INSERT INTO documents_fts(documents_fts, rowid, content, title, url, path)
+  VALUES('delete', old.id, old.content, json_extract(old.metadata, '$.title'), old.url, json_extract(old.metadata, '$.path'));
+END;
+
+-- Update trigger to maintain FTS index
+CREATE TRIGGER IF NOT EXISTS documents_fts_after_update AFTER UPDATE ON documents BEGIN
+  INSERT INTO documents_fts(documents_fts, rowid, content, title, url, path)
+  VALUES('delete', old.id, old.content, json_extract(old.metadata, '$.title'), old.url, json_extract(old.metadata, '$.path'));
+  INSERT INTO documents_fts(rowid, content, title, url, path)
+  VALUES(new.id, new.content, json_extract(new.metadata, '$.title'), new.url, json_extract(new.metadata, '$.path'));
+END;
+
+-- Insert trigger to maintain FTS index
+CREATE TRIGGER IF NOT EXISTS documents_fts_after_insert AFTER INSERT ON documents BEGIN
+  INSERT INTO documents_fts(rowid, content, title, url, path)
+  VALUES(new.id, new.content, json_extract(new.metadata, '$.title'), new.url, json_extract(new.metadata, '$.path'));
+END;

package/db/migrations/001-add-indexed-at-column.sql

@@ -0,0 +1,6 @@
+-- Add indexed_at column to track when documents were last indexed
+-- Step 1: Add the column allowing NULLs (SQLite limitation workaround)
+ALTER TABLE documents ADD COLUMN indexed_at DATETIME;
+
+-- Step 2: Update existing rows to set the timestamp
+UPDATE documents SET indexed_at = CURRENT_TIMESTAMP WHERE indexed_at IS NULL;