Xinghao MCP Server

中文文档

A small, modular Model Context Protocol (MCP) 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

.
├── 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

python -m venv .venv

Activate it on macOS or Linux:

source .venv/bin/activate

Activate it on Windows PowerShell:

.\.venv\Scripts\Activate.ps1

2. Install the project

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

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

3. Configure the environment

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

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:

python main.py

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

MCP_TRANSPORT=streamable-http
MCP_HOST=127.0.0.1
MCP_PORT=8000

Then run:

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:

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

docker compose up --build

After startup, connect to:

http://localhost:8000/mcp

Stop the service with:

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:

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.