💩(mcp) add a local MCP server configuration

This provides a way to start a local MCP server:
 - provided a user token, the MCP can create document
 - can be run locally and work with cursor or mcphost

Author: qbey

src/mcp_server/.dockerignore

@@ -0,0 +1,4 @@
+.venv
+.env
+docker-compose.yaml
+Dockerfile

src/mcp_server/.python-version

@@ -0,0 +1 @@
+3.12

src/mcp_server/Dockerfile

@@ -0,0 +1,35 @@
+FROM python:3.12-slim
+
+USER root
+
+# Install uv.
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Change the working directory to the `app` directory
+WORKDIR /app
+
+# Install dependencies
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --locked --no-install-project
+
+# Copy the application into the image
+COPY docs_mcp_server/ /app/docs_mcp_server/
+
+# Sync the project
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --locked
+
+# Attach ports
+EXPOSE 4200
+ENV SERVER_HOST=0.0.0.0
+
+# Un-privileged user running the application
+ARG DOCKER_USER
+USER ${DOCKER_USER}
+
+# Run the MCP server.
+CMD ["uv", "--no-cache", "run", "python", "-m" ,"docs_mcp_server.mcp_server"]

src/mcp_server/Makefile

@@ -0,0 +1,84 @@
+# /!\ /!\ /!\ /!\ /!\ /!\ /!\ DISCLAIMER /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\
+#
+# This Makefile is only meant to be used for DEVELOPMENT purpose as we are
+# changing the user id that will run in the container.
+#
+# PLEASE DO NOT USE IT FOR YOUR CI/PRODUCTION/WHATEVER...
+#
+# /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\ /!\
+#
+# Note to developers:
+#
+# While editing this file, please respect the following statements:
+#
+# 1. Every variable should be defined in the ad hoc VARIABLES section with a
+#    relevant subsection
+# 2. Every new rule should be defined in the ad hoc RULES section with a
+#    relevant subsection depending on the targeted service
+# 3. Rules should be sorted alphabetically within their section
+# 4. When a rule has multiple dependencies, you should:
+#    - duplicate the rule name to add the help string (if required)
+#    - write one dependency per line to increase readability and diffs
+# 5. .PHONY rule statement should be written after the corresponding rule
+# ==============================================================================
+# VARIABLES
+
+
+
+BOLD := \033[1m
+RESET := \033[0m
+GREEN := \033[1;32m
+
+# Use uv for package management
+UV = uv
+
+# ==============================================================================
+# RULES
+
+default: help
+
+help:  ## Display this help message
+	@echo "$(BOLD)Docs MCP server Makefile"
+	@echo "Please use 'make $(BOLD)target$(RESET)' where $(BOLD)target$(RESET) is one of:"
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(firstword $(MAKEFILE_LIST)) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "$(GREEN)%-30s$(RESET) %s\n", $$1, $$2}'
+.PHONY: help
+
+install:  ## Install the project
+	@$(UV) sync
+.PHONY: install
+
+install-dev:  ## Install the project with dev dependencies
+	@$(UV) sync --extra dev
+.PHONY: install-dev
+
+clean:  ## Clean the project folder
+	@rm -rf build/
+	@rm -rf dist/
+	@rm -rf *.egg-info
+	@find . -type d -name __pycache__ -exec rm -rf {} +
+	@find . -type f -name "*.pyc" -delete
+.PHONY: clean
+
+format:  ## Run the formatter
+	@$(UV) run ruff format
+.PHONY: format
+
+lint: format  ## Run the linter
+	@$(UV) run ruff check --fix .
+.PHONY: lint
+
+test:  ## Run the tests
+	@cd tests && PYTHON_PATH=.:$(PYTHON_PATH) $(UV) run python -m pytest . -vvv
+.PHONY: test
+
+runserver:  ## Run the project server
+	@$(UV) run python -m docs_mcp_server.mcp_server
+.PHONY: runserver
+
+runserver-docker:  ## Run the project server in a docker container
+	@touch .env
+	@docker compose up --watch
+.PHONY: runserver-docker
+
+run_llm:  ## Run the LLM server
+	@mcphost -m ollama:qwen2.5:3b --config "$(CWD)/mcphost.json"

src/mcp_server/README.md

@@ -0,0 +1,112 @@
+# mcp_server
+
+`mcp_server` is a backend server application designed to manage and process MCP requests.
+
+## Features
+
+- Create a new Docs with a title and markdown content from a request to an agentic LLM.
+
+
+## Configuration
+
+Configuration options can be set via environment variables or a configuration file (`.env`). 
+
+Common options include:
+
+- `SERVER_TRANSPORT`: `STDIO`, `SSE` or `STREAMABLE_HTTP` (default: `STDIO` locally or `STREAMABLE_HTTP` in the docker image)
+- `SERVER_PATH`: The base path of the server tools and resources (default: `/mcp/docs/`)
+
+You will need to set the following options to allow the MCP server to query Docs API:
+
+- `DOCS_API_URL`: The Docs base URL without the "/api/v1.0/" (default: `http://localhost:8071`)
+- `DOCS_API_TOKEN`: The API user token you generate from the Docs frontend
+
+You may customize the following options for local development, while it's not recommended and may break the Docker image:
+
+- `SERVER_HOST`: (default: `localhost` locally and `0.0.0.0` in the docker Image)
+- `SERVER_PORT`: (default: `4200`)
+
+Example when using the server from a Docker instance
+
+```dotenv
+SERVER_TRANSPORT=SSE
+
+DOCS_API_URL=http://host.docker.internal:8071/
+DOCS_API_TOKEN=<some_token>
+```
+
+## Run the MCP server
+
+### Local
+You may work on the MCP server project using local configuration with `uv`:
+
+```shell
+cd src/mcp_server
+
+make install
+make runserver
+```
+
+### Docker
+If you don't have local installation of Python or `uv` you can work using the Docker image:
+
+```shell
+cd src/mcp_server
+
+make runserver-docker
+```
+
+## Usage
+
+1. Create a local configuration file `.env`
+   
+   ```dotenv
+   SERVER_TRANSPORT=SSE
+
+   DOCS_API_URL=http://host.docker.internal:8071/
+   DOCS_API_TOKEN=your-token-here
+   ```
+   
+2. Run the server
+
+   ```shell
+   make runserver-docker
+   ```
+
+### In Cursor IDE
+
+In Cursor settings, in the MCP section, you can add a new MCP server with the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "url": "http://127.0.0.1:4200/mcp/docs/"
+    }
+  }
+}
+```
+
+### Locally with `mcphost` and `ollama`
+
+1. Install [mcphost](https://github.com/mark3labs/mcphost)
+2. Install [ollama](https://ollama.ai)
+3. Start ollama: `ollama serve`
+4. Pull an agentic model like Qwen2.5 `ollama pull qwen2.5:3b`
+5. Create an MCP configuration file (e.g. `mcphost.json`)
+   
+   ```json
+   {
+     "mcpServers": {
+       "docs": {
+         "url": "http://127.0.0.1:4200/mcp/docs/"
+       }
+     }
+   }
+   ```
+   
+6. Start mcphost
+
+   ```shell
+   mcphost -m ollama:qwen2.5:3b --config "$PWD/mcphost.json"
+   ```

src/mcp_server/docker-compose.yaml

@@ -0,0 +1,28 @@
+services:
+  docs_mcp-server:
+    build:
+      context: .
+      args:
+        DOCKER_USER: ${DOCKER_USER:-1000}
+    user: ${DOCKER_USER:-1000}
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    env_file:
+      - .env
+    ports:
+        - "4200:4200"
+
+    develop:
+      # Create a `watch` configuration to update the app
+      watch:
+        # Sync the working directory with the `/app` directory in the container
+        - action: sync+restart
+          path: ./docs_mcp_server
+          target: /app/docs_mcp_server/
+          # Exclude the project virtual environment
+          ignore:
+            - .venv/
+
+        # Rebuild the image on changes to the `pyproject.toml`
+        - action: rebuild
+          path: ./pyproject.toml

src/mcp_server/docs_mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""MCP Server package."""
+
+__version__ = "0.1.0"

src/mcp_server/docs_mcp_server/auth/__init__.py

@@ -0,0 +1 @@
+"""Authentication module for the MCP server."""

src/mcp_server/docs_mcp_server/auth/token.py

@@ -0,0 +1,16 @@
+"""Authentication against Docs API via user token."""
+
+import httpx
+
+
+class UserTokenAuthentication(httpx.Auth):
+    """Authentication class for request made to Docs, using the user token."""
+
+    def __init__(self, token):
+        """Initialize the authentication class with the user token."""
+        self.token = token
+
+    def auth_flow(self, request):
+        """Add the Authorization header to the request with the user token."""
+        request.headers["Authorization"] = f"Token {self.token}"
+        yield request

src/mcp_server/docs_mcp_server/constants.py

@@ -0,0 +1,11 @@
+"""Project constants."""
+
+import enum
+
+
+class TransportLayerEnum(enum.Enum):
+    """Enum for the MCP server transport layer types."""
+
+    STDIO = "stdio"
+    SSE = "sse"
+    STREAMABLE_HTTP = "streamable-http"

src/mcp_server/docs_mcp_server/mcp_server.py

@@ -0,0 +1,62 @@
+"""The core of the MCP server for the Docs API."""
+
+import asyncio
+
+import httpx
+from fastmcp import FastMCP
+
+from . import settings, utils
+from .auth.token import UserTokenAuthentication
+
+# Create a server instance from the OpenAPI spec
+mcp = FastMCP(name="Docs MCP Server")
+
+
+def setup_mcp_server():
+    """Configure the tools and resources for the MCP server."""
+    # Create a client for your API
+    api_client = httpx.AsyncClient(
+        base_url=settings.DOCS_API_URL,
+        auth=UserTokenAuthentication(token=settings.DOCS_API_TOKEN),
+    )
+
+    @mcp.tool()
+    async def create_document_tool(document_title: str, document_content: str) -> None:
+        """
+        Create a new document with the provided title and content.
+
+        Args:
+            document_title: The title of the document (required)
+            document_content: The content of the document (required)
+
+        """
+        # Get current user information
+        user_response = await api_client.get("/api/v1.0/users/me/")
+        user_response.raise_for_status()
+        user_data = user_response.json()
+
+        # Prepare document data
+        data = {
+            "title": document_title,
+            "content": document_content,
+            "sub": user_data["id"],
+            "email": user_data["email"],
+        }
+
+        # Create the document
+        create_response = await api_client.post(
+            "/api/v1.0/documents/create-for-owner/",
+            json=data,
+        )
+        create_response.raise_for_status()
+
+
+if __name__ == "__main__":
+    setup_mcp_server()
+    asyncio.run(utils.check_mcp(mcp))
+    mcp.run(
+        transport=settings.SERVER_TRANSPORT.value,
+        host=settings.SERVER_HOST,
+        port=settings.SERVER_PORT,
+        path=settings.SERVER_PATH,
+    )

src/mcp_server/docs_mcp_server/settings.py

@@ -0,0 +1,21 @@
+"""Settings for the MCP server."""
+
+import os
+
+from dotenv import load_dotenv
+
+from .constants import TransportLayerEnum
+
+load_dotenv()
+
+
+# Server settings
+SERVER_TRANSPORT = TransportLayerEnum[os.getenv("SERVER_TRANSPORT", "STDIO")]
+SERVER_HOST = str(os.getenv("SERVER_HOST", "localhost"))
+SERVER_PORT = int(os.getenv("SERVER_PORT", "4200"))
+SERVER_PATH = str(os.getenv("SERVER_PATH", "/mcp/docs"))
+
+
+# Docs related settings
+DOCS_API_URL = str(os.getenv("DOCS_API_URL", "http://localhost:8071"))
+DOCS_API_TOKEN = str(os.getenv("DOCS_API_TOKEN", "")) or None