@arabold/docs-mcp-server 1.3.0 → 1.4.1

package/README.md

@@ -17,103 +17,121 @@ The server exposes MCP tools for:
 - Finding appropriate versions (`find_version`).
 - Removing indexed documents (`remove_docs`).
 
-A companion CLI (`docs-mcp`) is also included for local management and interaction (note: the CLI `scrape` command waits for completion).
+## Usage
 
-## Building the Project
+Once the package is published to npm (`@arabold/docs-mcp-server`), you can run the server or the companion CLI in two main ways:
 
-Before you can use the server (e.g., by integrating it with Claude Desktop as described in the "Installation" section), you need to clone the repository and build the project from source.
+### Method 1: Global Installation (Recommended for CLI Usage)
 
-1.  **Clone the repository:**
-    If you haven't already, clone the project to your local machine:
+Install the package globally using npm. This makes the `docs-server` and `docs-cli` commands directly available in your terminal.
 
+1.  **Install Globally:**
     ```bash
-    git clone <repository-url> # Replace <repository-url> with the actual URL
-    cd docs-mcp-server
+    npm install -g @arabold/docs-mcp-server
     ```
-
-2.  **Install dependencies:**
-    Navigate into the project directory and install the required Node.js packages:
-
+2.  **Run the Server:**
     ```bash
-    npm install
+    docs-server
     ```
-
-3.  **Build the server:**
-    Compile the TypeScript source code into JavaScript. The output will be placed in the `dist/` directory. This step is necessary to generate the `dist/server.js` file referenced in the installation instructions.
-
+    _(Note: You'll need to manage environment variables like `OPENAI_API_KEY` yourself when running this way, e.g., by setting them in your shell profile or using a tool like `dotenv`.)_
+3.  **Run the CLI:**
     ```bash
-    npm run build
+    docs-cli <command> [options]
     ```
+    (See "CLI Command Reference" below for available commands and options.)
 
-After completing these steps and setting up your `.env` file (see "Environment Setup" under Development), you can proceed with the "Installation" or "Running with Docker" instructions.
-
-## Installation
+This method is convenient if you plan to use the `docs-cli` frequently.
 
-To use with Claude Desktop, add the server config:
+### Method 2: Running with Docker (Recommended for MCP Integration)
 
-- On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+Run the server using the pre-built Docker image available on GitHub Container Registry. This provides an isolated environment and simplifies setup.
 
-```json
-{
-  "mcpServers": {
-    "docs-mcp-server": {
-      "command": "node",
-      "args": ["/path/to/docs-mcp-server/dist/server.js"],
-      "env": {
-        "OPENAI_API_KEY": "sk-proj-..."
-      },
-      "disabled": false,
-      "autoApprove": []
-    }
-  }
-}
-```
-
-## Running with Docker
-
-Alternatively, you can build and run the server using Docker. This provides an isolated environment and exposes the server via HTTP endpoints.
-
-1.  **Build the Docker image:**
+1.  **Ensure Docker is installed and running.**
+2.  **Run the Server (e.g., for MCP Integration):**
 
     ```bash
-    docker build -t docs-mcp-server .
+    docker run -i --rm \
+      -e OPENAI_API_KEY="your-openai-api-key-here" \
+      -v docs-mcp-data:/data \
+      ghcr.io/arabold/docs-mcp-server:latest
     ```
 
-2.  **Run the Docker container:**
+    - `-i`: Keep STDIN open, crucial for MCP communication over stdio.
+    - `--rm`: Automatically remove the container when it exits.
+    - `-e OPENAI_API_KEY="..."`: **Required.** Set your OpenAI API key.
+    - `-v docs-mcp-data:/data`: **Required for persistence.** Mounts a Docker named volume `docs-mcp-data` to the container's `/data` directory, where the database is stored. You can replace `docs-mcp-data` with a specific host path if preferred (e.g., `-v /path/on/host:/data`).
+    - `ghcr.io/arabold/docs-mcp-server:latest`: Specifies the public Docker image to use.
+
+    This is the recommended approach for integrating with tools like Claude Desktop or Cline.
+
+    **Claude/Cline Configuration Example:**
+    Add the following configuration block to your MCP settings file (adjust path as needed):
+
+    - Cline: `/Users/andrerabold/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+    - Claude Desktop (MacOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
+    - Claude Desktop (Windows): `%APPDATA%/Claude/claude_desktop_config.json`
+
+    ```json
+    {
+      "mcpServers": {
+        "docs-mcp-server": {
+          "command": "docker",
+          "args": [
+            "run",
+            "-i",
+            "--rm",
+            "-e",
+            "OPENAI_API_KEY",
+            "-v",
+            "docs-mcp-data:/data",
+            "ghcr.io/arabold/docs-mcp-server:latest"
+          ],
+          "env": {
+            "OPENAI_API_KEY": "sk-proj-..." // Required: Replace with your key
+          },
+          "disabled": false,
+          "autoApprove": []
+        }
+        // ... other servers might be listed here
+      }
+    }
+    ```
 
-    Make sure your `.env` file is present in the project root directory, as it contains the necessary `OPENAI_API_KEY`. The container will read variables from this file at runtime using the `--env-file` flag. (See "Environment Setup" under Development for details on the `.env` file).
+    Remember to replace `"sk-proj-..."` with your actual OpenAI API key and restart the application.
 
+3.  **Run the CLI (Requires Docker):**
+    To use the CLI commands, you can run them inside a temporary container:
     ```bash
-    docker run -p 8000:8000 --env-file .env --name docs-mcp-server-container docs-mcp-server
+    docker run --rm \
+      -e OPENAI_API_KEY="your-openai-api-key-here" \
+      -v docs-mcp-data:/data \
+      ghcr.io/arabold/docs-mcp-server:latest \
+      npx docs-cli <command> [options]
     ```
+    (See "CLI Command Reference" below for available commands and options.)
 
-    - `-p 8000:8000`: Maps port 8000 on your host to port 8000 in the container.
-    - `--env-file .env`: Loads environment variables from your local `.env` file at runtime. This is the recommended way to handle secrets.
-    - `--name docs-mcp-server-container`: Assigns a name to the container for easier management.
+This method is ideal for integrating the server into other tools and ensures a consistent runtime environment.
 
-3.  **Available Endpoints:**
+## CLI Command Reference
 
-    Once the container is running, the MCP server is accessible via:
+The `docs-cli` provides commands for managing the documentation index. Access it either via global installation (`docs-cli ...`) or `npx` (`npx -y --package=@arabold/docs-mcp-server docs-cli ...`).
 
-    - **SSE Endpoint:** `http://localhost:8000/sse` (for Server-Sent Events communication)
-    - **POST Messages:** `http://localhost:8000/message` (for sending individual messages)
+**General Help:**
 
-This method is useful if you prefer not to run the server directly via Node.js or integrate it with Claude Desktop using the standard installation method.
-
-## CLI Usage
+```bash
+docs-cli --help
+# or
+npx -y --package=@arabold/docs-mcp-server docs-cli --help
+```
 
-The `docs-mcp` CLI provides commands for managing documentation. To see available commands and options:
+**Command Specific Help:** (Replace `docs-cli` with the `npx...` command if not installed globally)
 
 ```bash
-# Show all commands
-docs-mcp --help
-
-# Show help for a specific command
-docs-mcp scrape --help
-docs-mcp search --help
-docs-mcp find-version --help
-docs-mcp remove --help
+docs-cli scrape --help
+docs-cli search --help
+docs-cli find-version --help
+docs-cli remove --help
+docs-cli list-libraries --help
 ```
 
 ### Scraping Documentation (`scrape`)
@@ -121,7 +139,7 @@ docs-mcp remove --help
 Scrapes and indexes documentation from a given URL for a specific library.
 
 ```bash
-docs-mcp scrape <library> <url> [options]
+docs-cli scrape <library> <url> [options]
 ```
 
 **Options:**
@@ -137,17 +155,11 @@ docs-mcp scrape <library> <url> [options]
 **Examples:**
 
 ```bash
-# Scrape React 18.2.0 docs
-docs-mcp scrape react --version 18.2.0 https://react.dev/
-
-# Scrape React docs without a specific version (indexed as unversioned)
-docs-mcp scrape react https://react.dev/
-
-# Scrape partial version (will be stored as 7.0.0)
-docs-mcp scrape semver --version 7 https://github.com/npm/node-semver
+# Scrape React 18.2.0 docs (assuming global install)
+docs-cli scrape react --version 18.2.0 https://react.dev/
 
-# Scrape pre-release version
-docs-mcp scrape mylib --version 2.0.0-rc.1 https://mylib.com/docs
+# Scrape React docs without a specific version (using npx)
+npx -y --package=@arabold/docs-mcp-server docs-cli scrape react https://react.dev/
 ```
 
 ### Searching Documentation (`search`)
@@ -155,7 +167,7 @@ docs-mcp scrape mylib --version 2.0.0-rc.1 https://mylib.com/docs
 Searches the indexed documentation for a library, optionally filtering by version.
 
 ```bash
-docs-mcp search <library> <query> [options]
+docs-cli search <library> <query> [options]
 ```
 
 **Options:**
@@ -172,19 +184,10 @@ docs-mcp search <library> <query> [options]
 
 ```bash
 # Search latest React docs for 'hooks'
-docs-mcp search react 'hooks'
-
-# Search React 18.x docs for 'hooks'
-docs-mcp search react --version 18.x 'hooks'
-
-# Search React 17 docs (will match 17.x.x or older if 17.x.x not found)
-docs-mcp search react --version 17 'hooks'
+docs-cli search react 'hooks'
 
-# Search only React 18.0.0 docs
-docs-mcp search react --version 18.0.0 --exact-match 'hooks'
-
-# Search only unversioned React docs
-docs-mcp search react --version "" 'hooks'
+# Search React 18.x docs for 'hooks' (using npx)
+npx -y --package=@arabold/docs-mcp-server docs-cli search react --version 18.x 'hooks'
 ```
 
 ### Finding Available Versions (`find-version`)
@@ -192,7 +195,7 @@ docs-mcp search react --version "" 'hooks'
 Checks the index for the best matching version for a library based on a target, and indicates if unversioned documents exist.
 
 ```bash
-docs-mcp find-version <library> [options]
+docs-cli find-version <library> [options]
 ```
 
 **Options:**
@@ -203,13 +206,7 @@ docs-mcp find-version <library> [options]
 
 ```bash
 # Find the latest indexed version for react
-docs-mcp find-version react
-
-# Find the best match for react version 17.x
-docs-mcp find-version react --version 17.x
-
-# Find the best match for react version 17.0.0 (may fall back to older)
-docs-mcp find-version react --version 17.0.0
+docs-cli find-version react
 ```
 
 ### Listing Libraries (`list-libraries`)
@@ -217,7 +214,7 @@ docs-mcp find-version react --version 17.0.0
 Lists all libraries currently indexed in the store.
 
 ```bash
-docs-mcp list-libraries
+docs-cli list-libraries
 ```
 
 ### Removing Documentation (`remove`)
@@ -225,7 +222,7 @@ docs-mcp list-libraries
 Removes indexed documents for a specific library and version.
 
 ```bash
-docs-mcp remove <library> [options]
+docs-cli remove <library> [options]
 ```
 
 **Options:**
@@ -236,10 +233,7 @@ docs-mcp remove <library> [options]
 
 ```bash
 # Remove React 18.2.0 docs
-docs-mcp remove react --version 18.2.0
-
-# Remove unversioned React docs
-docs-mcp remove react
+docs-cli remove react --version 18.2.0
 ```
 
 ### Version Handling Summary
@@ -248,70 +242,122 @@ docs-mcp remove react
 - **Searching/Finding:** Accepts specific versions, partials, or ranges (`X.Y.Z`, `X.Y`, `X`, `X.x`). Falls back to the latest older version if the target doesn't match. Omitting the version targets the latest available. Explicitly searching `--version ""` targets unversioned documents.
 - **Unversioned Docs:** Libraries can have documentation stored without a specific version (by omitting `--version` during scrape). These can be searched explicitly using `--version ""`. The `find-version` command will also report if unversioned docs exist alongside any semver matches.
 
-## Development
+## Development & Advanced Setup
 
-For details on the project's architecture and design principles, please see [ARCHITECTURE.md](ARCHITECTURE.md).
+This section covers running the server/CLI directly from the source code for development purposes. The primary usage method is now via the public Docker image as described in "Method 2".
 
-_Notably, the vast majority of this project's code was generated by the AI assistant Cline, leveraging the capabilities of this very MCP server._
+### Running from Source (Development)
 
-## Releasing
+This provides an isolated environment and exposes the server via HTTP endpoints.
 
-This project uses [semantic-release](https://github.com/semantic-release/semantic-release) and [Conventional Commits](https://www.conventionalcommits.org/) to automate the release process.
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different
+    cd docs-mcp-server
+    ```
+2.  **Create `.env` file:**
+    Copy the example and add your OpenAI key (see "Environment Setup" below).
+    ```bash
+    cp .env.example .env
+    # Edit .env and add your OPENAI_API_KEY
+    ```
+3.  **Build the Docker image:**
+    ```bash
+    docker build -t docs-mcp-server .
+    ```
+4.  **Run the Docker container:**
 
-**How it works:**
+    ```bash
+    # Option 1: Using a named volume (recommended)
+    # Docker automatically creates the volume 'docs-mcp-data' if it doesn't exist on first run.
+    docker run -i --env-file .env -v docs-mcp-data:/data --name docs-mcp-server docs-mcp-server
 
-1.  **Commit Messages:** All commits merged into the `main` branch **must** follow the Conventional Commits specification. This allows `semantic-release` to automatically determine the type of changes (feature, fix, breaking change, etc.).
-    - `feat:` commits trigger a `minor` release.
-    - `fix:` commits trigger a `patch` release.
-    - Commits with `BREAKING CHANGE:` in the footer or `!` after the type/scope (e.g., `feat!:`) trigger a `major` release.
-    - Other types (`chore:`, `docs:`, `style:`, `refactor:`, `test:`, etc.) do not trigger a release by themselves.
-2.  **Automation:** When commits with release-triggering types (`feat`, `fix`, `BREAKING CHANGE`) are pushed or merged to the `main` branch, the "Release" GitHub Actions workflow automatically runs `semantic-release`.
-3.  **`semantic-release` Actions:** The tool performs the following steps automatically:
-    - Determines the next semantic version number based on the commits.
-    - Updates the `CHANGELOG.md` file with the relevant commits.
-    - Updates the `version` in `package.json`.
-    - Commits the updated `CHANGELOG.md` and `package.json`.
-    - Creates a Git tag for the new version (e.g., `v1.2.3`).
-    - Publishes the package to npm.
-    - Creates a corresponding GitHub Release with the generated release notes.
+    # Option 2: Mapping to a host directory
+    # docker run -i --env-file .env -v /path/on/your/host:/data --name docs-mcp-server docs-mcp-server
+    ```
 
-**What you need to do:**
+    - `-i`: Keep STDIN open even if not attached. This is crucial for interacting with the server over stdio.
+    - `--env-file .env`: Loads environment variables (like `OPENAI_API_KEY`) from your local `.env` file.
+    - `-v docs-mcp-data:/data` or `-v /path/on/your/host:/data`: **Crucial for persistence.** This mounts a Docker named volume (Docker creates `docs-mcp-data` automatically if needed) or a host directory to the `/data` directory inside the container. The `/data` directory is where the server stores its `documents.db` file (as configured by `DOCS_MCP_STORE_PATH` in the Dockerfile). This ensures your indexed documentation persists even if the container is stopped or removed.
+    - `--name docs-mcp-server`: Assigns a convenient name to the container.
 
-- **Use Conventional Commits:** Strictly adhere to the Conventional Commits format for all your commit messages. The commit hooks (`commitlint`) will help enforce this.
-- **Merge to `main`:** Merge your feature branches into `main` when they are ready.
+    The server inside the container now runs directly using Node.js and communicates over **stdio**.
 
-**You do _not_ need to manually:**
+This method is useful for contributing to the project or running un-published versions.
 
-- Update the `CHANGELOG.md`.
-- Bump the version number in `package.json`.
-- Create Git tags.
-- Publish to npm.
-- Create GitHub releases.
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different
+    cd docs-mcp-server
+    ```
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+3.  **Build the project:**
+    This compiles TypeScript to JavaScript in the `dist/` directory.
+    ```bash
+    npm run build
+    ```
+4.  **Setup Environment:**
+    Create and configure your `.env` file as described in "Environment Setup" below. This is crucial for providing the `OPENAI_API_KEY`.
 
-The automation handles all of these steps based on your commit history on the `main` branch.
+5.  **Run:**
+    - **Server (Development Mode):** `npm run dev:server` (builds, watches, and restarts)
+    - **Server (Production Mode):** `npm run start` (runs pre-built code)
+    - **CLI:** `npm run cli -- <command> [options]` or `node dist/cli.js <command> [options]`
 
-### Environment Setup
+### Environment Setup (for Source/Docker)
 
-**Note:** This `.env` file setup is primarily needed when running the server manually (e.g., `node dist/server.js`) or during local development/testing using the CLI (`docs-mcp`). When configuring the server for Claude Desktop (see "Installation"), the `OPENAI_API_KEY` is typically set directly in the `claude_desktop_config.json` file, and this `.env` file is not used by the Claude integration.
+**Note:** This `.env` file setup is primarily needed when running the server from source or using the Docker method. When using the `npx` integration method, the `OPENAI_API_KEY` is set directly in the MCP configuration file.
 
 1. Create a `.env` file based on `.env.example`:
-
-```bash
-cp .env.example .env
-```
-
+   ```bash
+   cp .env.example .env
+   ```
 2. Update your OpenAI API key in `.env`:
 
-```
-OPENAI_API_KEY=your-api-key-here
-```
+   ```
+   # Required: Your OpenAI API key for generating embeddings.
+   OPENAI_API_KEY=your-api-key-here
 
-### Debugging
+   # Optional: Specify a custom directory to store the SQLite database file (documents.db).
+   # If set, this path takes precedence over the default locations.
+   # Default behavior (if unset):
+   # 1. Uses './.store/' in the project root if it exists (legacy).
+   # 2. Falls back to OS-specific data directory (e.g., ~/Library/Application Support/docs-mcp-server on macOS).
+   # DOCS_MCP_STORE_PATH=/path/to/your/desired/storage/directory
+   ```
 
-Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
+### Debugging (from Source)
+
+Since MCP servers communicate over stdio when run directly via Node.js, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script after building:
 
 ```bash
 npx @modelcontextprotocol/inspector node dist/server.js
 ```
 
 The Inspector will provide a URL to access debugging tools in your browser.
+
+### Releasing
+
+This project uses [semantic-release](https://github.com/semantic-release/semantic-release) and [Conventional Commits](https://www.conventionalcommits.org/) to automate the release process.
+
+**How it works:**
+
+1.  **Commit Messages:** All commits merged into the `main` branch **must** follow the Conventional Commits specification.
+2.  **Automation:** The "Release" GitHub Actions workflow automatically runs `semantic-release` on pushes to `main`.
+3.  **`semantic-release` Actions:** Determines version, updates `CHANGELOG.md` & `package.json`, commits, tags, publishes to npm, and creates a GitHub Release.
+
+**What you need to do:**
+
+- Use Conventional Commits.
+- Merge to `main`.
+
+**Automation handles:** Changelog, version bumps, tags, npm publish, GitHub releases.
+
+### Architecture
+
+For details on the project's architecture and design principles, please see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+_Notably, the vast majority of this project's code was generated by the AI assistant Cline, leveraging the capabilities of this very MCP server._

package/dist/{chunk-75KNYK47.js → chunk-BD7OFN4H.js}

@@ -1679,8 +1679,9 @@ var RemoveTool = class {
 };
 
 // src/store/DocumentManagementService.ts
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import path3 from "node:path";
+import envPaths from "env-paths";
 import Fuse from "fuse.js";
 import semver3 from "semver";
 
@@ -11273,8 +11274,33 @@ var DocumentManagementService = class {
     return (version ?? "").toLowerCase();
   }
   constructor() {
-    const dbPath = path3.join(process.cwd(), ".store", "documents.db");
-    mkdirSync(path3.dirname(dbPath), { recursive: true });
+    let dbPath;
+    let dbDir;
+    const envStorePath = process.env.DOCS_MCP_STORE_PATH;
+    if (envStorePath) {
+      dbDir = envStorePath;
+      dbPath = path3.join(dbDir, "documents.db");
+      logger.debug(`\u{1F4BE} Using database directory from DOCS_MCP_STORE_PATH: ${dbDir}`);
+    } else {
+      const oldDbDir = path3.join(process.cwd(), ".store");
+      const oldDbPath = path3.join(oldDbDir, "documents.db");
+      const oldDbExists = existsSync(oldDbPath);
+      if (oldDbExists) {
+        dbPath = oldDbPath;
+        dbDir = oldDbDir;
+        logger.debug(`\u{1F4BE} Using legacy database path: ${dbPath}`);
+      } else {
+        const standardPaths = envPaths("docs-mcp-server", { suffix: "" });
+        dbDir = standardPaths.data;
+        dbPath = path3.join(dbDir, "documents.db");
+        logger.debug(`\u{1F4BE} Using standard database directory: ${dbDir}`);
+      }
+    }
+    try {
+      mkdirSync(dbDir, { recursive: true });
+    } catch (error) {
+      logger.error(`\u26A0\uFE0F Failed to create database directory ${dbDir}: ${error}`);
+    }
     this.store = new DocumentStore(dbPath);
     this.documentRetriever = new DocumentRetrieverService(this.store);
     const minChunkSize = 500;
@@ -11498,4 +11524,4 @@ export {
   RemoveTool,
   DocumentManagementService
 };
-//# sourceMappingURL=chunk-75KNYK47.js.map
+//# sourceMappingURL=chunk-BD7OFN4H.js.map