# Xinghao MCP Server

[中文文档](README.zh.md)

A small, modular [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server built with Python and FastMCP. It includes working examples of tools, prompts, and resources, plus a reusable async client for connecting to external APIs.

This repository is intended as a practical starting point for developing a custom MCP server.

## Features

- Python 3.11+ and the official MCP Python SDK
- `stdio`, `sse`, and `streamable-http` transports
- Centralized configuration through environment variables
- Explicit registration for tools, prompts, and resources
- Async `httpx` client base for external API integrations
- Docker and Docker Compose support
- Registry and tool tests with pytest

## Built-in MCP Capabilities

| Type | Name or URI | Description |
| --- | --- | --- |
| Tool | `health_check` | Returns the service status and current UTC time |
| Tool | `add` | Adds two numbers |
| Tool | `subtract` | Subtracts the second number from the first |
| Prompt | `welcome_prompt` | Creates a prompt for welcoming a new team member |
| Resource | `server://info` | Returns basic server information as JSON |

## Project Structure

```text
.
├── app/
│   ├── base/            # Shared API client and result types
│   ├── prompts/         # MCP prompt implementations and registration
│   ├── resources/       # MCP resource implementations and registration
│   ├── tools/           # MCP tool implementations and registration
│   ├── config.py        # Environment-based settings
│   └── server.py        # FastMCP instance and component registration
├── tests/               # Registry and tool tests
├── .env.example         # Environment variable template
├── docker-compose.yaml
├── Dockerfile
├── main.py              # Application entry point
└── pyproject.toml       # Package metadata and dependencies
```

## Getting Started

### 1. Create a virtual environment

```bash
python -m venv .venv
```

Activate it on macOS or Linux:

```bash
source .venv/bin/activate
```

Activate it on Windows PowerShell:

```powershell
.\.venv\Scripts\Activate.ps1
```

### 2. Install the project

For local development, install the package and test dependencies in editable mode:

```bash
python -m pip install -e ".[dev]"
```

### 3. Configure the environment

Copy `.env.example` to `.env`, then adjust the values if needed:

```dotenv
MCP_TRANSPORT=stdio
MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_API_BASE_URL=
MCP_API_KEY=
```

| Variable | Default | Description |
| --- | --- | --- |
| `MCP_TRANSPORT` | `stdio` | Transport: `stdio`, `sse`, or `streamable-http` |
| `MCP_HOST` | `127.0.0.1` | Bind address for network transports |
| `MCP_PORT` | `8000` | Bind port for network transports |
| `MCP_API_BASE_URL` | Empty | Base URL used by the reusable external API client |
| `MCP_API_KEY` | Empty | Optional API key sent as the `X-API-Key` header |

The external API settings are only needed by tools that use `app.base.api_client.APIClient`.

### 4. Run the server

The default `stdio` transport is suitable for local MCP clients:

```bash
python main.py
```

To start a network transport, update `MCP_TRANSPORT` in `.env`. For example:

```dotenv
MCP_TRANSPORT=streamable-http
MCP_HOST=127.0.0.1
MCP_PORT=8000
```

Then run:

```bash
python main.py
```

The Streamable HTTP endpoint is available at `http://127.0.0.1:8000/mcp`.

## Connect an MCP Client

For a client that launches local MCP servers over `stdio`, use a configuration like this and replace the paths with absolute paths on your machine:

```json
{
  "mcpServers": {
    "xinghao-mcp-server": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/xinghao-mcp-server/main.py"]
    }
  }
}
```

On Windows, the command typically points to `.venv\\Scripts\\python.exe`.

## Docker

The Compose configuration starts the server with Streamable HTTP on port `8000`:

```bash
docker compose up --build
```

After startup, connect to:

```text
http://localhost:8000/mcp
```

Stop the service with:

```bash
docker compose down
```

## Extending the Server

### Add a tool

1. Define a typed function in `app/tools/`.
2. Import it in `app/tools/__init__.py`.
3. Register it inside `register_tools()` with `mcp.tool()`.

FastMCP uses the function signature and docstring to generate the tool schema and description.

### Add a prompt

Define the prompt function in `app/prompts/`, then register it in `register_prompts()` with `mcp.prompt()`.

### Add a resource

Define the resource function in `app/resources/`, then register it in `register_resources()` with a URI such as `mcp.resource("example://item")`.

### Call an external API

Use or extend `app.base.api_client.APIClient` for async JSON `GET` and `POST` requests. It reads the configured base URL and can attach an API key through the `X-API-Key` header.

## Testing

Run the test suite:

```bash
python -m pytest
```

The current tests verify the built-in tool behavior and confirm that all tools, prompts, and resources are registered.

## License

No license file is currently included. Add a license before distributing or reusing this project outside its intended scope.