Merge pull request #4 from baruchiro/official-mcp

Add HTTP Transport Mode, Docker Support, and Migrate to Official MCP SDK

Author: nloui

.cursor/rules/http-transport.mdc

@@ -0,0 +1,13 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# HTTP Transport Mode for MCP Server
+
+- The MCP server can run in HTTP mode using the `--http` CLI flag.
+- When `--http` is set, the entrypoint [src/index.ts](mdc:src/index.ts) starts an Express server and exposes the MCP API at `/mcp`.
+- Each POST to `/mcp` creates a new `McpServer` and `StreamableHTTPServerTransport` for stateless, isolated handling.
+- The HTTP port can be set with `--port` (default: 3000).
+- Express must be installed as a dependency for HTTP mode.
+- If `--http` is not set, the server runs in stdio mode as before.

.cursor/rules/typescript-mcp-migration.mdc

@@ -0,0 +1,12 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# TypeScript MCP Server Migration
+
+- The main entrypoint is [src/index.ts](mdc:src/index.ts), which starts an MCP server for Paperless-NGX using the @modelcontextprotocol/sdk package.
+- All core logic is now in TypeScript; all main files in src/ use the .ts extension.
+- The MCP server is started using `McpServer` and `StdioServerTransport` from the SDK, with `await server.connect(transport)`.
+- The project can be run directly in TypeScript using the npm script: `npm run start -- <baseUrl> <token>` (see [package.json](mdc:package.json)).
+- Node.js types are provided by @types/node in devDependencies.

.dockerignore

@@ -0,0 +1,2 @@
+node_modules
+build 

.github/workflows/docker-build.yml

@@ -0,0 +1,18 @@
+name: Docker Build (PR)
+on:
+  pull_request:
+    branches:
+      - '**'
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Build Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          push: false

.github/workflows/docker-publish.yml

@@ -0,0 +1,38 @@
+name: Docker Publish
+on:
+  push:
+    branches:
+      - master
+      - main
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.actor }}/${{ github.repository }}
+          flavor: |
+            latest=true
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }} 

.gitignore

@@ -1,8 +1,5 @@
 # Dependencies
 node_modules/
-package-lock.json
-yarn.lock
-pnpm-lock.yaml
 
 # Environment variables
 .env

Dockerfile

@@ -1,25 +1,19 @@
-# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
-# Use a Node.js base image
-FROM node:18-alpine AS build
-
-# Set the working directory
+# Builder stage
+FROM node:20-slim AS builder
 WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
 
-# Copy package.json and package-lock.json
-COPY package.json /app/
-
-# Install dependencies
-RUN npm install
-
-# Copy the rest of the application
-COPY . /app
+# Production stage
+FROM node:20-slim AS production
 
-# Expose the port the app runs on
-EXPOSE 8080
-
-# Define environment variable for base URL and token
-ENV BASE_URL=http://your-paperless-instance:8000
-ENV TOKEN=your-api-token
+WORKDIR /app
+COPY --from=builder /app/build .
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+COPY --from=builder /app/package-lock.json ./package-lock.json
 
-# Command to run the application
-CMD ["node", "src/index.js", "$BASE_URL", "$TOKEN"]
+EXPOSE 3000
+ENTRYPOINT [ "node", "index.js", "--http", "--port", "3000" ]

README.md

@@ -335,3 +335,27 @@ The server is built with:
 ## API Documentation
 
 This MCP server implements endpoints from the Paperless-NGX REST API. For more details about the underlying API, see the [official documentation](https://docs.paperless-ngx.com/api/).
+
+## Running the MCP Server
+
+The MCP server can be run in two modes:
+
+### 1. stdio (default)
+
+This is the default mode. The server communicates over stdio, suitable for CLI and direct integrations.
+
+```
+npm run start -- <baseUrl> <token>
+```
+
+### 2. HTTP (Streamable HTTP Transport)
+
+To run the server as an HTTP service, use the `--http` flag. You can also specify the port with `--port` (default: 3000). This mode requires [Express](https://expressjs.com/) to be installed (it is included as a dependency).
+
+```
+npm run start -- <baseUrl> <token> --http --port 3000
+```
+
+- The MCP API will be available at `POST /mcp` on the specified port.
+- Each request is handled statelessly, following the [StreamableHTTPServerTransport](https://github.com/modelcontextprotocol/typescript-sdk) pattern.
+- GET and DELETE requests to `/mcp` will return 405 Method Not Allowed.