MCP-BOS: 可扩展的MCP服务器框架
MCP-BOS: 模块化、可扩展的Model Context Protocol服务器框架
使用基于约定的自动模块发现机制，为Claude Desktop打造的灵活MCP服务器框架。通过简洁的模块接口和声明式配置，轻松扩展AI应用功能，无需修改核心代码。支持FastMCP标准，包含完整工具、资源和提示模板注册能力。
特性
- 🧩 模块化设计：功能以自包含模块组织，便于扩展
- 🔍 自动发现：约定优于配置的模块加载方式
- ⚙️ 声明式配置：通过config.json灵活配置模块和参数
- 🔌 即插即用：新功能只需添加符合接口的模块目录
- 🔒 安全稳定：分层架构确保核心系统稳定可靠
- 📝 详细日志：完善的日志系统便于调试与监控
- 🖥️ Claude Desktop集成：与Claude深度集成，提供AI增强体验
技术栈
Python FastMCP Model Context Protocol Claude Desktop JSON 模块化设计 微内核架构
架构思想
MCP-BOS框架采用了现代化的模块化架构设计，主要设计理念包括：
模块化设计
整个框架以模块为中心，每个功能都被封装在独立的模块中，使功能扩展变得简单直观。模块之间相互独立，但又通过标准接口相互协作，形成一个完整的服务生态。
自动发现机制
框架能够自动发现modules目录下的模块，无需手动注册每个模块。这种"约定优于配置"的方式大幅降低了扩展成本。
声明式配置
通过config.json文件进行全局和模块级别的配置，使框架具有很高的灵活性，可以根据不同需求启用或禁用特定模块。
分层架构
框架分为核心层和模块层，核心层负责框架基础功能，模块层负责具体业务功能，这种分层设计使框架更加健壮和可维护。
目录结构说明
mcp-bos/
├── config.json # 全局配置文件
├── main.py # 主入口文件
├── core/ # 核心系统
│ ├── __init__.py
│ ├── module_registry.py # 模块注册表
│ ├── module_loader.py # 模块加载器
│ ├── module_interface.py # 模块接口定义
│ ├── config_manager.py # 配置管理器
│ └── server.py # FastMCP服务器适配
├── modules/ # 功能模块目录
│ ├── __init__.py
│ ├── hello_world/ # Hello World示例模块
│ │ ├── __init__.py
│ │ └── hello.py
│ └── ... # 其他功能模块
├── utils/ # 工具函数
│ ├── __init__.py
│ └── helpers.py
└── README.md # 项目文档
核心组件说明
- main.py: 框架入口点，负责初始化和启动服务器
- core/: 核心组件目录
- module_interface.py: 定义所有模块必须实现的接口
- module_registry.py: 管理已注册的模块
- module_loader.py: 自动发现和加载模块
- config_manager.py: 加载和管理配置
- server.py: 与FastMCP集成，提供服务器功能
- modules/: 功能模块目录，每个子目录是一个独立模块
- utils/: 通用工具函数
配置文件结构
config.json文件是框架的核心配置，分为全局配置和模块配置两部分：
{
"global": {
"server_name": "MCP-BOS",
"debug": true,
"log_level": "INFO",
"transport": "stdio",
"dependencies": ["mcp[cli]"]
},
"modules": {
"hello_world": {
"enabled": true,
"message": "Hello, {}!"
},
"module_name": {
"enabled": false,
"param1": "value1"
}
}
}
-
global: 全局配置部分
- server_name: 服务器名称
- debug: 是否启用调试模式
- log_level: 日志级别
- transport: 传输协议，通常为"stdio"
- dependencies: 依赖包列表
-
modules: 模块配置部分，每个模块有自己的配置节
- enabled: 是否启用该模块
- 其他模块特定的配置参数
使用方法
安装
- 克隆仓库:
git clone https://github.com/kinbos/mcp-bos.git
cd mcp-bos
- 安装依赖:
uv pip install mcp[cli]
配置
编辑config.json文件来配置服务器和模块：
- 设置服务器名称、日志级别等全局参数
- 启用或禁用模块
- 配置模块特定参数
运行
有以下几种方式运行服务器:
- 直接运行:
python main.py
- 使用uv运行:
uv run main.py
- 与Claude Desktop集成:
# 使用mcp CLI集成到Claude Desktop
mcp install main.py
- 开发调试模式:
# 使用mcp Inspector测试服务器
mcp inspect main.py
添加新模块
- 在
modules目录下创建一个新的模块目录:
mkdir modules/my_module
- 创建必要的文件:
touch modules/my_module/__init__.py
touch modules/my_module/my_module.py
- 实现模块接口:
# modules/my_module/my_module.py
from core.module_interface import ModuleInterface
class MyModule(ModuleInterface):
def get_info(self):
return {
"name": "my_module",
"version": "1.0.0",
"description": "我的自定义模块",
"author": "kinbos 严富坤",
"email": "fookinbos@gmail.com",
"website": "htttps://www.yanfukun.com"
}
def register(self, server):
@server.tool()
def my_tool(param: str) -> str:
"""自定义工具"""
return f"处理参数: {param}"
@server.resource("my://resource")
def my_resource() -> str:
"""自定义资源"""
return "资源内容"
- 导出模块类:
# modules/my_module/__init__.py
from modules.my_module.my_module import MyModule
__all__ = ['MyModule']
- 在配置文件中启用模块:
{
"modules": {
"my_module": {
"enabled": true,
"custom_param": "value"
}
}
}
- 重启服务器，新模块将被自动发现和加载
常见问题
模块未加载
- 检查模块目录结构是否正确
- 确认
__init__.py文件是否导出了模块类 - 检查配置文件中模块是否启用
- 查看日志输出，了解详细错误信息
编码问题
如果在Windows环境下遇到中文编码问题，确保设置了正确的环境变量:
"env": {
"PYTHONIOENCODING": "utf-8"
}
服务器连接问题
- 确认Claude Desktop已正确配置
- 检查依赖是否正确安装
- 查看Claude Desktop日志文件
贡献指南
欢迎提交贡献，请遵循以下步骤:
- Fork项目
- 创建功能分支
- 提交更改
- 创建Pull Request
作者
- kinbos 严富坤 - 个人网站
- 邮箱: fookinbos@gmail.com