# 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).

```bash
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:

```bash
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:

```bash
# 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)

```bash
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:

```python
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:

```bash
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
1) Open Claude Desktop
2) Go to Settings → Developer → Model Context Protocol (MCP) Servers
3) 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):

```text
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):

```json
{
  "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%`):

```json
{
  "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:

```json
{
  "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
1) Open or start a new chat
2) Ensure the MCP server `project-info-mcp` appears in the tools list (depending on UI version)
3) Ask Claude to list MCP resources. You should see one resource with URI:
   - `mcp://project-info-mcp/project_info` and `mime_type: text/markdown`
4) 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:

```bash
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

1) Build the image (from the project root):
   ```bash
   docker build -t project-info-mcp:latest .
   ```

2) Start the MCP Inspector UI:
   ```bash
   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.

3) 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
     ```

4) 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)

1) Install deps and run the server locally:
   ```bash
   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.

2) Start the MCP Inspector UI:
   ```bash
   npx -y @modelcontextprotocol/inspector
   ```

3) 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.

4) 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):
    ```bash
    python -m fastmcp dev -- command python main.py
    ```
  - This is optional; using `npx @modelcontextprotocol/inspector` directly is sufficient.