使用说明

mcp基地

光秃秃的骨头 FastMCP 服务器模板。以此为起点，无需从头开始即可构建自己的MCP服务器。

MCP（模型上下文协议）是一个开放标准，允许AI助手调用外部工具和服务。此模板通过HTTP实现MCP，因此任何兼容MCP的AI应用程序都可以访问您的服务器。

先决条件

码头工人 --对于Docker Compose部署路径
紫外线 --有关源部署路径（请参见安装uv)
Node.js --git提交钩子所必需的；钩子使用提交规范检查强制执行常规提交，这是用于提交消息验证的同类最佳Node.js工具

自定义模板

1.复制模板

在GitHub上 --点击 使用此模板→ 创建新仓库。这创建了一个没有分叉关系和模板历史的干净副本。

没有GitHub --克隆、删除历史记录并重新初始化：

git clone https://github.com/sesopenko/mcp-base.git my-project
cd my-project
rm -rf .git
git init
git add .
git commit -m "chore: bootstrap from mcp-base template"

2.自定义身份值

编辑 project.env 设置自己的值（Docker镜像名称、包名称、项目名称、描述），然后运行安装脚本在整个存储库中替换它们：

bash scripts/apply-project-config.sh

该脚本是幂等的，可以安全地多次运行。

快速开始

选项A——Docker编写

创建一个 docker-compose.yml:

services:
  mcp-base:
    image: sesopenko/mcp-base:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.toml:/config/config.toml:ro
    restart: unless-stopped

复制示例配置并对其进行编辑：
```
cp config.toml.example config.toml
```
启动服务器：
```
docker compose up -d
```

选项B——从源运行

安装紫外线如果你还没有。
安装依赖项：
```
uv sync
```
复制示例配置并对其进行编辑：
```
cp config.toml.example config.toml
```
启动服务器：
```
uv run python -m mcp_base
```

安全

此服务器具有 无需认证 在其MCP端点上。它仅设计用于局域网。

请勿将此服务器直接暴露于互联网。

如果您需要远程访问它，请将其放置在处理TLS终止和访问控制的反向代理后面。配置反向代理不在此项目范围内。

配置

创建一个 config.toml 在工作目录中（或传递 --config <path>):

[server]
host = "0.0.0.0"
port = 8080

[logging]
level = "info"

[服务器]

密钥	默认值	描述
`host`	`"0.0.0.0"`	MCP服务器监听的地址。 `0.0.0.0` 绑定所有接口。
`port`	`8080`	MCP服务器侦听的端口

[日志记录]

密钥	默认值	描述
`level`	`"info"`	日志冗长。什么之中的一个： `debug`, `info`, `warning`, `error`.

连接AI应用程序

此服务器使用 可流式传输的HTTP MCP运输。客户端通过HTTP POST与流式响应进行通信——在浏览器中打开端点将返回 Not Acceptable 错误，这是预期的。

将兼容MCP的AI应用程序指向服务器的MCP端点：

http://<host>:<port>/mcp

例如，如果服务器正在运行 192.168.1.10 使用默认端口：

http://192.168.1.10:8080/mcp

有关如何注册MCP服务器，请参阅您的AI应用程序的文档。确保它支持流式HTTP传输（大多数现代MCP客户端都支持）。

系统提示示例

对于系统提示，XML比markdown更受欢迎，因为显式命名标签给出了明确的语义含义——人工智能总是确切地知道每个块包含什么。Markdown标题需要推理，更容易被误解。

复制并调整此提示，为您的AI助手提供使用工具的明确指导。

小贴士——让法学硕士为你写这篇文章。 XML结构化系统提示很有效，但大多数开发人员都不熟悉，手工编写也很乏味。与任何有能力的LLM进行快速对话（描述你的工具、它们的作用以及你希望助手如何表现），都会产生一个结构良好的提示，你可以直接进入。结果通常比纯文本或markdown手动编写的任何东西都要好。

XML标签的作用就像带标签的文件夹——模型确切地知道每条信息的起点和终点

训练数据充满了结构化标记，因此模型已经在标签中自然地“思考”了

标签可防止模型将您的说明与其正在处理的内容混淆

<system>
  <role>
    You are a helpful assistant with access to an MCP server. Use the available
    tools to fulfil user requests accurately and efficiently.
  </role>
  <tools>
    <tool name="health_check">Check that the MCP server is running and reachable.</tool>
  </tools>
  <guidelines>
    <item>Call health_check if the user asks whether the server is available.</item>
  </guidelines>
</system>

可用工具

工具	说明
`health_check`	退货 `{"status": "ok"}` 确认服务器正在运行。

工具在实施过程中记录在此处。

建筑

模板遵循干净的三层分离：

文件	目的
`src/mcp_base/tools.py`	纯Python函数——每个工具一个函数，没有框架耦合
`src/mcp_base/server.py`	FastMCP接线——用寄存器记录工具功能 `@mcp.tool()` 并运行服务器
`src/mcp_base/config.py`	TOML配置加载-类型化数据类 `[server]` 和 `[logging]` 章节
`src/mcp_base/logging.py`	结构化记录器工厂

添加工具

向添加功能 src/mcp_base/tools.py 带有谷歌风格的文档字符串和完整类型的注释。
将函数导入 src/mcp_base/server.py 并在以下网址注册 @mcp.tool().
在中添加单元测试 tests/unit/.
向中添加一行 可用工具 此README中的表。

运行测试

uv run pytest tests/unit/

贡献/维护

看维护.md 用于设置、开发命令、AI代理轨道以及如何运行测试。

许可证

该项目根据 GNU通用公共许可证v3.0.

致谢：骑在巨人的背上

这个项目是在克劳德代码，由Anthropic开发的AI编码助手。

像Claude这样的人工智能助手接受了大量数据的培训，其中大部分是由开源社区编写的：开发人员自由贡献的库、工具、文档和数十年的共享知识。没有这个基础，这样的工具是不可能的。

鉴于该债务，该项目根据 GNU通用公共许可证v3.0GPL确保此代码以及任何衍生作品保持开源。这是一个小小的互惠行为：回馈公地，使之成为可能。

对于每一位将提交推送到公共仓库、编写Stack Overflow答案或在开放许可证下发布包的开发人员——谢谢。