MCP-BOS

MCP-BOS

一个模块化、可扩展的模型上下文协议服务器框架，专为 Claude Desktop 设计，它采用基于约定的自动模块发现机制，以便在不修改核心代码的情况下轻松扩展 AI 应用程序的功能。

Category
访问服务器

README

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
  1. 安装依赖:
uv pip install mcp[cli]

配置

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

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

运行

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

  1. 直接运行:
python main.py
  1. 使用uv运行:
uv run main.py
  1. 与Claude Desktop集成:
# 使用mcp CLI集成到Claude Desktop
mcp install main.py
  1. 开发调试模式:
# 使用mcp Inspector测试服务器
mcp inspect main.py

添加新模块

  1. 在modules目录下创建一个新的模块目录:
mkdir modules/my_module
  1. 创建必要的文件:
touch modules/my_module/__init__.py
touch modules/my_module/my_module.py
  1. 实现模块接口:
# 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 "资源内容"
  1. 导出模块类:
# modules/my_module/__init__.py
from modules.my_module.my_module import MyModule

__all__ = ['MyModule']
  1. 在配置文件中启用模块:
{
  "modules": {
    "my_module": {
      "enabled": true,
      "custom_param": "value"
    }
  }
}
  1. 重启服务器，新模块将被自动发现和加载

常见问题

模块未加载

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

编码问题

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

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

服务器连接问题

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

贡献指南

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

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

作者

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

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
  1. 安装依赖:
uv pip install mcp[cli]

配置

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

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

运行

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

  1. 直接运行:
python main.py
  1. 使用uv运行:
uv run main.py
  1. 与Claude Desktop集成:
# 使用mcp CLI集成到Claude Desktop
mcp install main.py
  1. 开发调试模式:
# 使用mcp Inspector测试服务器
mcp inspect main.py

添加新模块

  1. 在modules目录下创建一个新的模块目录:
mkdir modules/my_module
  1. 创建必要的文件:
touch modules/my_module/__init__.py
touch modules/my_module/my_module.py
  1. 实现模块接口:
# 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 "资源内容"
  1. 导出模块类:
# modules/my_module/__init__.py
from modules.my_module.my_module import MyModule

__all__ = ['MyModule']
  1. 在配置文件中启用模块:
{
  "modules": {
    "my_module": {
      "enabled": true,
      "custom_param": "value"
    }
  }
}
  1. 重启服务器，新模块将被自动发现和加载

常见问题

模块未加载

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

编码问题

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

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

服务器连接问题

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

贡献指南

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

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

作者

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

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选