feat(docker): add configurable storage path & improve support

This commit significantly enhances Docker support and introduces a configurable storage path for the database, simplifying installation and deployment.

- **Configurable Storage:** Introduced the `DOCS_MCP_STORE_PATH` environment variable to allow users to specify a custom directory for the `documents.db` file. The path resolution order is now:
    1. `DOCS_MCP_STORE_PATH` (if set)
    2. Legacy `./.store/` directory (if `documents.db` exists there)
    3. Standard OS-specific application data directory
- **Docker Enhancements:**
    - Updated the Dockerfile to use `node:22-slim`, expose a `/data` volume, and set `DOCS_MCP_STORE_PATH=/data`.
    - Added a new GitHub Actions workflow (`docker-publish.yml`) to build and publish the Docker image to GHCR.
    - Updated the README.md to recommend Docker as the primary installation method, providing clear instructions and an updated MCP configuration example.
    - Refined `.dockerignore` for a smaller build context.
- **CI/CD Updates:** Removed `--ignore-scripts` from `npm ci` commands in workflows to align with Docker build process.
- **Dependency Management:** Updated `prepare` script in `package.json` for better compatibility (`husky || true`).

Author: arabold

.clineignore

@@ -5,3 +5,4 @@ dist/
 *.log
 .env.*
 !.env.example
+!.github/

.dockerignore

@@ -4,9 +4,17 @@ Dockerfile
 
 # Version control
 .git
+.github
+.husky
 
 # Already in gitignore but explicitly listed for Docker context
 node_modules
 dist
 *.log
 .env*
+
+# Other
+.store
+README.md
+ARCHITECTURE.md
+CHANGELOG.md

.env.example

@@ -1,2 +1,9 @@
 # OpenAI
 OPENAI_API_KEY=your-key-here
+
+# 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

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
           cache: 'npm'
 
       - name: Install dependencies
-        run: npm ci --ignore-scripts
+        run: npm ci
 
       - name: Run linter
         run: npm run lint
@@ -41,7 +41,7 @@ jobs:
           cache: 'npm'
 
       - name: Install dependencies
-        run: npm ci --ignore-scripts
+        run: npm ci
 
       - name: Run tests
         run: npm run test
@@ -61,7 +61,7 @@ jobs:
           cache: 'npm'
 
       - name: Install dependencies
-        run: npm ci --ignore-scripts
+        run: npm ci
 
       - name: Run build
         run: npm run build

.github/workflows/docker-publish.yml

@@ -0,0 +1,49 @@
+# .github/workflows/docker-publish.yml
+name: Docker Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*' # Trigger only on version tags like v1.0.0, v1.2.3, etc.
+
+jobs:
+  publish:
+    name: Build and Push Docker Image to GHCR
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # Needed to check out the code
+      packages: write # Needed to push Docker image to GHCR
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }} # Use the GitHub username initiating the workflow
+          password: ${{ secrets.GITHUB_TOKEN }} # Use the automatically generated token
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }} # Use ghcr.io/arabold/docs-mcp-server
+          tags: |
+            # Extract version number from the Git tag (e.g., v1.2.3 -> 1.2.3)
+            type=semver,pattern={{version}}
+            # Also tag with 'v' prefix (e.g., v1.2.3)
+            type=semver,pattern={{raw}}
+            # Add the 'latest' tag
+            type=raw,value=latest,enable={{is_default_branch}} # Only add latest tag if the tag is on the default branch (usually main) - semantic-release should ensure this
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/publish.yml

@@ -29,7 +29,7 @@ jobs:
           cache: 'npm'
 
       - name: Install dependencies
-        run: npm ci --ignore-scripts
+        run: npm ci
 
       - name: Run build
         run: npm run build

Dockerfile

@@ -1,13 +1,13 @@
 # Build stage
-FROM node:20-alpine AS builder
+FROM node:22-slim AS builder
 
 WORKDIR /app
 
 # Copy package files
 COPY package*.json ./
 
 # Install dependencies
-RUN npm ci --ignore-scripts
+RUN npm ci
 
 # Copy source code
 COPY . .
@@ -16,20 +16,22 @@ COPY . .
 RUN npm run build
 
 # Production stage
-FROM node:20-alpine
+FROM node:22-slim
 
 WORKDIR /app
 
 # Copy package files
 COPY package*.json ./
 
 # Install production dependencies only
-RUN npm ci --omit=dev --ignore-scripts
+RUN npm ci --omit=dev
 
 # Copy built files from builder
 COPY --from=builder /app/dist ./dist
 
+# Define the data directory environment variable and volume
+ENV DOCS_MCP_STORE_PATH=/data
+VOLUME /data
+
 # Set the command to run the application
-# CMD ["node", "dist/index.cjs"]
-EXPOSE 8000
-CMD ["npx", "-y", "supergateway", "--stdio", "node", "dist/server.js"]
+CMD ["node", "dist/server.js"]

README.md

@@ -42,17 +42,27 @@ Install the package globally using npm. This makes the `docs-server` and `docs-c
 
 This method is convenient if you plan to use the `docs-cli` frequently.
 
-### Method 2: Direct Execution with `npx` (Recommended for MCP Integration)
+### Method 2: Running with Docker (Recommended for MCP Integration)
 
-Run the server or CLI directly using `npx` without needing a global installation. The `-y` flag ensures the package is automatically downloaded if needed.
+Run the server using the pre-built Docker image available on GitHub Container Registry. This provides an isolated environment and simplifies setup.
 
-1.  **Run the Server (e.g., for MCP Integration):**
+1.  **Ensure Docker is installed and running.**
+2.  **Run the Server (e.g., for MCP Integration):**
 
     ```bash
-    npx -y --package=@arabold/docs-mcp-server docs-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
     ```
 
-    This is the recommended approach for integrating with tools like Claude Desktop or Cline, as it avoids polluting the global namespace and ensures the correct version is used.
+    - `-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` is created automatically if it doesn't exist) 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):
@@ -65,8 +75,17 @@ Run the server or CLI directly using `npx` without needing a global installation
     {
       "mcpServers": {
         "docs-mcp-server": {
-          "command": "npx",
-          "args": ["-y", "--package=@arabold/docs-mcp-server", "docs-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
           },
@@ -80,13 +99,18 @@ Run the server or CLI directly using `npx` without needing a global installation
 
     Remember to replace `"sk-proj-..."` with your actual OpenAI API key and restart the application.
 
-2.  **Run the CLI:**
+3.  **Run the CLI (Requires Docker):**
+    To use the CLI commands, you can run them inside a temporary container:
     ```bash
-    npx -y --package=@arabold/docs-mcp-server docs-cli <command> [options]
+    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.)
 
-This method is ideal for one-off executions or when integrating the server into other tools.
+This method is ideal for integrating the server into other tools and ensures a consistent runtime environment.
 
 ## CLI Command Reference
 
@@ -220,9 +244,9 @@ docs-cli remove react --version 18.2.0
 
 ## Development & Advanced Setup
 
-This section covers running the server/CLI using Docker or directly from the source code for development purposes.
+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".
 
-### Running with Docker
+### Running from Source (Development)
 
 This provides an isolated environment and exposes the server via HTTP endpoints.
 
@@ -244,20 +268,22 @@ This provides an isolated environment and exposes the server via HTTP endpoints.
 4.  **Run the Docker container:**
 
     ```bash
-    docker run -p 8000:8000 --env-file .env --name docs-mcp-server-container docs-mcp-server
+    # 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
+
+    # 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
     ```
 
-    - `-p 8000:8000`: Maps host port 8000 to container port 8000.
-    - `--env-file .env`: Loads environment variables from your local `.env`.
-    - `--name docs-mcp-server-container`: Assigns a container name.
+    - `-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.
 
-5.  **Available Endpoints:**
-    - SSE: `http://localhost:8000/sse`
-    - POST Messages: `http://localhost:8000/message`
+    The server inside the container now runs directly using Node.js and communicates over **stdio**.
 
-### Running from Source (Development)
-
-This method is required for contributing to the project or running un-published versions.
+This method is useful for contributing to the project or running un-published versions.
 
 1.  **Clone the repository:**
     ```bash
@@ -290,8 +316,17 @@ This method is required for contributing to the project or running un-published
    cp .env.example .env
    ```
 2. Update your OpenAI API key in `.env`:
+
    ```
+   # Required: Your OpenAI API key for generating embeddings.
    OPENAI_API_KEY=your-api-key-here
+
+   # 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
    ```
 
 ### Debugging (from Source)

package.json

@@ -19,7 +19,7 @@
     "package.json"
   ],
   "scripts": {
-    "prepare": "husky",
+    "prepare": "husky || true",
     "build": "tsup",
     "cli": "node --enable-source-maps dist/cli.js",
     "start": "node --enable-source-maps dist/server.js",

src/store/DocumentManagementService.test.ts

@@ -53,14 +53,6 @@ vi.mock("./DocumentRetrieverService", () => ({
   DocumentRetrieverService: vi.fn().mockImplementation(() => mockRetriever),
 }));
 
-vi.mock("../utils/logger", () => ({
-  logger: {
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-
 // --- END MOCKS ---
 
 describe("DocumentManagementService", () => {
@@ -86,7 +78,7 @@ describe("DocumentManagementService", () => {
     await docService?.shutdown();
   });
 
-  // --- NEW: Constructor Path Logic Tests ---
+  // --- Constructor Path Logic Tests ---
   describe("Constructor Database Path Selection", () => {
     // Add beforeEach specific to this suite for memfs reset
     beforeEach(() => {
@@ -125,6 +117,36 @@ describe("DocumentManagementService", () => {
       // Verify the standard directory was created in memfs
       expect(vol.existsSync(path.dirname(expectedStandardDbPath))).toBe(true);
     });
+
+    it("should use the path from DOCS_MCP_STORE_PATH environment variable if set", () => {
+      const mockEnvStorePath = "/mock/env/store/path";
+      const expectedEnvDbPath = path.join(mockEnvStorePath, "documents.db");
+      const originalEnvValue = process.env.DOCS_MCP_STORE_PATH; // Store original value
+      process.env.DOCS_MCP_STORE_PATH = mockEnvStorePath; // Set env var
+
+      try {
+        // Ensure neither old nor standard paths exist initially for isolation
+        // (vol.reset() in beforeEach should handle this)
+
+        // Instantiate LOCALLY for this specific test
+        const localDocService = new DocumentManagementService();
+
+        // Verify DocumentStore was called with the env var path
+        expect(vi.mocked(DocumentStore)).toHaveBeenCalledWith(expectedEnvDbPath);
+        // Verify the env var directory was created in memfs
+        expect(vol.existsSync(mockEnvStorePath)).toBe(true);
+        // Verify other paths were NOT created (optional but good check)
+        expect(vol.existsSync(path.dirname(expectedOldDbPath))).toBe(false);
+        expect(vol.existsSync(path.dirname(expectedStandardDbPath))).toBe(false);
+        // Verify envPaths was NOT called
+        expect(mockEnvPathsFn).not.toHaveBeenCalled();
+        // Verify fs.existsSync was NOT called for the old path check
+        // (We need to spy on fs.existsSync for this) - Let's skip this assertion for now as it requires more mock setup
+      } finally {
+        // Restore original env var value
+        process.env.DOCS_MCP_STORE_PATH = originalEnvValue;
+      }
+    });
   });
   // --- END: Constructor Path Logic Tests ---