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 模块化设计 微内核架构

架构思想

!img.png

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: 是否启用该模块
  • 其他模块特定的配置参数

使用方法

安装

1. 克隆仓库:

git clone https://github.com/kinbos/mcp-bos.git
cd mcp-bos

2. 安装依赖:

uv pip install mcp[cli]

配置

编辑config.json文件来配置服务器和模块：

1. 设置服务器名称、日志级别等全局参数
2. 启用或禁用模块
3. 配置模块特定参数

运行

有以下几种方式运行服务器:

1. 直接运行:

python main.py

2. 使用uv运行:

uv run main.py

3. 与Claude Desktop集成:

# 使用mcp CLI集成到Claude Desktop
mcp install main.py

4. 开发调试模式:

# 使用mcp Inspector测试服务器
mcp inspect main.py

添加新模块

1. 在modules目录下创建一个新的模块目录:

mkdir modules/my_module

2. 创建必要的文件:

touch modules/my_module/__init__.py
touch modules/my_module/my_module.py

3. 实现模块接口:

# 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 "资源内容"

4. 导出模块类:

# modules/my_module/__init__.py
from modules.my_module.my_module import MyModule

__all__ = ['MyModule']

5. 在配置文件中启用模块:

{
  "modules": {
    "my_module": {
      "enabled": true,
      "custom_param": "value"
    }
  }
}

6. 重启服务器，新模块将被自动发现和加载

常见问题

模块未加载

• 检查模块目录结构是否正确
• 确认__init__.py文件是否导出了模块类
• 检查配置文件中模块是否启用
• 查看日志输出，了解详细错误信息

编码问题

如果在Windows环境下遇到中文编码问题，确保设置了正确的环境变量:

"env": {
  "PYTHONIOENCODING": "utf-8"
}

服务器连接问题

• 确认Claude Desktop已正确配置
• 检查依赖是否正确安装
• 查看Claude Desktop日志文件

贡献指南

欢迎提交贡献，请遵循以下步骤:

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 创建Pull Request

作者

• kinbos 严富坤 - 个人网站
• 邮箱: fookinbos@gmail.com

Shared threads will appear here, showcasing real-world applications and insights from the community. Check back soon for updates!