mcp-server by ziutus - MCP Server

Project Info MCP — HTTP Transport + Docker Setup

This repository contains a minimal FastMCP 2.x server that exposes a single resource: the file project_info.md (served as text/markdown).

It now uses FastMCP's built‑in HTTP transport (no separate FastAPI server). The service listens on port 8000 and speaks the Model Context Protocol over HTTP. This is intended for MCP‑aware clients (e.g., Claude Desktop, dev tools), not as a generic REST API.

Below you will find instructions to:

Build and run the server with Docker Desktop
Configure Claude Desktop to launch the server inside Docker and communicate with it over stdio (MCP command transport)

Prerequisites

Docker Desktop installed and running
Optional (local testing without Docker): Python 3.13+ with fastmcp>=2,<3
Claude Desktop (with MCP support)

Build the Docker image

Run these commands from the project root (where the Dockerfile lives).

docker build -t project-info-mcp:latest .

Notes:

The image uses python:3.13-slim and installs fastmcp>=2,<3.
The container’s working directory is /app and it runs python main.py by default.

Run the container (manual test)

The MCP server runs over HTTP on port 8000. You can run the container interactively to see logs:

docker run --rm -it project-info-mcp:latest

If you want the container to serve your current local project_info.md (so edits are reflected live), mount it read-only, and publish port 8000:

# Windows PowerShell (from project root)
docker run --rm -i -p 8000:8000 -v "$PWD/project_info.md:/app/project_info.md:ro" project-info-mcp:latest

# macOS/Linux
docker run --rm -i -p 8000:8000 -v "${PWD}/project_info.md:/app/project_info.md:ro" project-info-mcp:latest

Tip (Windows CMD): replace $PWD with %CD%.

Run as a service with Docker Compose (optional)

docker compose up --build
# stop with
docker compose down

This is useful for keeping the container running while you exec/attach for debugging. The Compose file maps 8000:8000 for HTTP transport.

Using FastMCP HTTP transport

The server code follows the FastMCP HTTP transport pattern:

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

@mcp.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="http", port=8000)

In this repository, we expose a resource instead of a tool. See main.py for the concrete implementation. Start the server locally with:

pip install -e .
python main.py
# MCP is listening on http://127.0.0.1:8000

Note: MCP over HTTP is not a human‑friendly REST API. Use an MCP‑capable client to connect.

Configure Claude Desktop to use the container

Claude Desktop can launch MCP servers via a command transport. We will point it to docker run ... so it starts the container on-demand and communicates over stdio.

You have two configuration methods. Pick one.

Option A: Configure via Claude Desktop UI

Open Claude Desktop
Go to Settings → Developer → Model Context Protocol (MCP) Servers
Add new MCP server:
- Name: project-info-mcp
- Command: docker
- Arguments:
```
run --rm -i project-info-mcp:latest
```
- Save

If you want the server to read your host project_info.md, add a bind mount in Arguments (be careful with quoting on Windows):

run --rm -i 
  -v ${PWD}/project_info.md:/app/project_info.md:ro 
  project-info-mcp:latest

On Windows PowerShell, ${PWD} expands to the current directory. In CMD, use %CD%. If quoting is problematic in the UI, you can instead use the JSON file method below where multi-arg arrays are clearer.

Option B: Configure via claude_desktop_config.json

Create or edit the config file at the platform path below and add an entry under mcpServers.

Windows: %APPDATA%/Claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Minimal config (no bind mount):

{
  "mcpServers": {
    "project-info-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "project-info-mcp:latest"
      ]
    }
  }
}

Config with bind mount to serve your local project_info.md read-only:

Windows (PowerShell uses $PWD; for CMD replace with %CD%):

{
  "mcpServers": {
    "project-info-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${PWD}/project_info.md:/app/project_info.md:ro",
        "project-info-mcp:latest"
      ]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "project-info-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${PWD}/project_info.md:/app/project_info.md:ro",
        "project-info-mcp:latest"
      ]
    }
  }
}

After saving the config, restart Claude Desktop.

Verify in Claude Desktop

Open or start a new chat
Ensure the MCP server project-info-mcp appears in the tools list (depending on UI version)
Ask Claude to list MCP resources. You should see one resource with URI:
- mcp://project-info-mcp/project_info and mime_type: text/markdown
Ask Claude to read the project_info resource; it should return the contents of project_info.md.

Troubleshooting

Docker command not found: ensure Docker Desktop is installed and running.
Permission/volume errors on Windows: try running PowerShell as Administrator, or use %CD% (CMD) or a full path for the -v mount.
No resources listed in Claude: check Claude’s developer settings and logs; confirm the container starts (you should see logs in the Claude console). Try running the container manually to confirm it works: docker run --rm -it project-info-mcp:latest.
project_info.md changes not reflected: verify you added the -v mount to bind the host file into /app/project_info.md in the container.

Local (non-Docker) run

If you prefer to test locally without Docker:

pip install -e .
python main.py

Claude Desktop config (command transport) would then point to python with args ["main.py"] instead of docker run ....

Reference

Resource URI exposed by the server: mcp://project-info-mcp/project_info
MIME type: text/markdown
Base image: python:3.13-slim
Main entrypoint: python main.py

Test with MCP Inspector (npx @modelcontextprotocol/inspector)

Use the official MCP Inspector to validate and debug the server. This works with the Dockerized server or a local Python run.

Prerequisites

Node.js 18+ (includes npx). Install from https://nodejs.org if needed.
Your server code from this repo (already set up).
Optional: Docker Desktop if you want to run the containerized server.

Option A — Inspect the Dockerized server

Build the image (from the project root):

docker build -t project-info-mcp:latest .

Start the MCP Inspector UI:
```
npx -y @modelcontextprotocol/inspector
```
- This opens the Inspector in your browser (or prints a local URL). If a browser doesn’t open automatically, copy the URL from the terminal and paste it in your browser.
Connect the Inspector to your server using Command (stdio):
- Click “Connect”.
- Transport: choose “Command”.
- Command: docker
- Arguments (no bind mount):
```
run --rm -i project-info-mcp:latest
```
- Click “Connect”. The Inspector will launch the container and communicate over stdio.
Optional: If you want live reads of your host file project_info.md, add a bind mount (adjust path syntax for your shell/OS):
- Windows PowerShell:
```
run --rm -i -v ${PWD}/project_info.md:/app/project_info.md:ro project-info-mcp:latest
```
- Windows CMD (use %CD% instead of ${PWD}) or macOS/Linux (use ${PWD}):
```
run --rm -i -v ${PWD}/project_info.md:/app/project_info.md:ro project-info-mcp:latest
```
Exercise the server in the Inspector:
- Use the Resources panel to “List” resources.
- You should see mcp://project-info-mcp/project_info with mime_type: text/markdown.
- Click/execute a “Read Resource” action and select that URI. The Inspector will show the contents of project_info.md.

Option B — Inspect a locally-run server (no Docker)

Install deps and run the server locally:
```
pip install -e .
python main.py
```
(Or with uv: uv run python main.py)

Note: You don’t have to start the server first if you use Inspector’s Command transport—Inspector can launch it for you. See next step.
Start the MCP Inspector UI:
```
npx -y @modelcontextprotocol/inspector
```
Connect via Command (stdio):
- Click “Connect”.
- Transport: “Command”.
- Command: python
- Arguments:
```
main.py
```
- Click “Connect”. The Inspector will launch python main.py and speak MCP over stdio.
List and read resources as above.

What you should see/verify

A single resource listed: mcp://project-info-mcp/project_info.
Reading the resource returns the contents of your project_info.md.
If project_info.md is missing, the server returns a short markdown message asking you to create it.

Tips and troubleshooting (Inspector)

Docker flags:
- Use -i (interactive stdin). Do not add -t when launching via Inspector, as a TTY can interfere with stdio framing.
Windows paths/quoting:
- PowerShell uses ${PWD}; CMD uses %CD%. If quoting is tricky in the Inspector UI, try the local (non‑Docker) path first to confirm connectivity.
If no resources appear:
- Check the Inspector’s connection log (left/bottom panel) for startup errors.
- Try running the server outside Inspector to ensure it starts: docker run --rm -it project-info-mcp:latest or python main.py.
Node requirement:
- If npx isn’t found, install Node.js. On corporate machines, you may need a proxy configured for npm.
FastMCP CLI (alternative):
- If you have fastmcp installed, it offers a dev helper that shells out to the Inspector and wires a proxy for you. Example (syntax may vary across versions):
```
python -m fastmcp dev -- command python main.py
```
- This is optional; using npx @modelcontextprotocol/inspector directly is sufficient.