💩(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,131 @@
+# 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 if you want 
+  to use token based authentication (default: `None`). If not provided, the server will 
+  use the authentication forwarder (pass the incoming authentication header to the Docs API call).
+
+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"
+   ```
+
+
+## About the authentication forwarder
+
+The authentication forwarder is a simple proxy that forwards the authentication header from 
+the incoming request to the Docs API call. This allows to use "resource server" authentication.
+
+For instance:
+
+- Docs authentication is based on OIDC with Keycloak.
+- The AI chat is using the same Keycloak instance for authentication.
+- You can store the access token in the chat session and use it when calling the MCP server.
+- The MCP server will forward the access token to the Docs API call 
+  (actually, it forwards the whole authentication header).
+- Docs will introspect the access token and authenticate the user.
+- Conclusion: the user will be able to create a new Doc with the same access token 
+  used in the chat session.

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/forwarder.py

@@ -0,0 +1,18 @@
+"""Authentication against Docs API via user token."""
+
+import httpx
+from fastmcp.server.dependencies import get_http_request
+
+
+class HeaderForwarderAuthentication(httpx.Auth):
+    """Authentication class for request made to Docs, work as boilerplate."""
+
+    def auth_flow(self, request):
+        """Get Authorization header from request and pass it to the client."""
+        _incoming_request = get_http_request()
+
+        # Get authorization header
+        auth_header = _incoming_request.headers.get("authorization", "")
+
+        request.headers["Authorization"] = auth_header
+        yield request

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