超越MCP服务器
一个全面的库，用于构建具有OAuth和工作流功能的基于Deno的MCP（模型上下文协议）服务器。
🤖 推荐：用Beyond Better构建
我们强烈建议使用 超越更好 开发您的MCP服务器应用程序！
Beyond Better是一款基于人工智能的项目助理，它彻底改变了您构建MCP服务器的方式：
为什么Beyond更适合MCP开发？
- 🎯 项目范围内的情报：BB了解您的整个MCP服务器结构，使复杂的实现更容易
- 💬 智能对话：在人工智能的帮助下讨论架构、调试问题并改进实现
- ⚡ 代码生成：生成样板，实施工作流程，并自动遵循最佳实践
- 📚 全面的指导方针：使用我们面向消费者的BB指南以获得最佳效果
- 🔄 同步文档：保持MCP服务器指令与代码更改同步
- 🛠️ 自定义工具：使用MCP特定的测试和验证工具扩展BB
Beyond Better快速入门
选项1：超越更好的云 （最简单-推荐）
- 注册：参观 Beyond better应用程序
- 创建项目：通过浏览器UI添加您的MCP项目
- 配置准则：添加
guidelines-create-app.md在项目设置中 - 开始建立：与BB聊天以生成您的MCP服务器
所有配置都通过直观的浏览器界面进行管理，无需命令行！
选项2：自托管/仅本地模式 （开源）
# 1. Install Beyond Better CLI
curl -sSL https://raw.githubusercontent.com/Beyond-Better/bb/main/install.sh | sh
# 2. Create your MCP project
mkdir my-mcp-server && cd my-mcp-server
# 3. Initialize BB
bb init
# 4. Start development with guidelines
bb start
# In BB, reference: "Use guidelines from @beyondbetter/bb-mcp-server guidelines-create-app.md"📖 消费者指南：参见 指南-create-app.md 有关使用此库构建MCP服务器的全面说明。这些指南是专门为LLM和Beyond Better设计的。
🔗 超越更好的资源:
______________________________________________________________________
🚀 用户快速入门
使用我们的示例应用程序，在几分钟内开始构建自己的MCP服务器！
安装
# Install from JSR registry
deno add jsr:@beyondbetter/bb-mcp-server📚 示例应用程序（推荐学习路径）
我们提供 4个渐进式示例 它教你从基本工具到高级OAuth集成的一切：
| 示例 | 复杂性 | 焦点 | 你将学到什么 |
|---|---|---|---|
| 1-简单 | ⭐ 初学者 | 基本工具和插件 | 从最简单的设置开始 |
| 双插件工作流程 | ⭐⭐ 中级 | 多步骤工作流 | 何时使用工作流与工具 |
| 3-plugin-api-auth | ⭐⭐⭐ 高级 | OAuth和API集成 | 第三方API身份验证 |
| 4-手动存款 | ⭐⭐⭐⭐ 专家 | 完全定制 | 完整的基础设施控制 |
🎯 从示例1开始-简单MCP服务器
# Clone and run the simplest example
git clone https://github.com/beyond-better/bb-mcp-server.git
cd bb-mcp-server/examples/1-simple
# Copy environment template and configure
cp .env.example .env
# Run the MCP server
deno run --allow-all --unstable-kv main.ts✨ 你从盒子里得到了什么：
- ✅ 使用插件发现的MCP服务器
- ✅ 基本实用工具（日期时间、系统信息、JSON验证）
- ✅ STDIO和HTTP传输支持
- ✅ 基于环境的配置
- ✅ 全面的日志记录和错误处理
📖 完整入门指南
👉 有关详细的设置说明、体系结构说明和分步教程，请参阅 示例/README.md
examples目录包含您需要的一切：
- 🏃♂️ 快速奔跑 使用工作代码
- 📚 循序渐进地学习 从简单概念到高级概念
- 🧪 查看测试模式 用于验证和调试
- 🛠️ 用作模板 用于您自己的MCP服务器实现
图书馆使用（无示例）
💡 刚开始构建MCP服务器？ 结账 指南-create-app.md 了解全面的模式和最佳实践。这些指导方针非常适用 超越更好 人工智能辅助开发。
如果你喜欢从头开始：
import { AppServer } from 'jsr:@beyondbetter/bb-mcp-server';
// Create and start server with minimal configuration
const appServer = await AppServer.create({
serverConfig: {
name: 'my-mcp-server',
version: '1.0.0',
title: 'My MCP Server',
description: 'My custom MCP server implementation',
},
// Optional: plugin configuration
pluginConfig: {
discoveryPaths: ['./src/plugins'],
autoLoad: true,
},
});
await appServer.start();直接从JSR运行示例
您可以直接运行任何示例，而无需克隆存储库：
# Run the simple example
deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/1-simple
# Run the plugin-workflows example
deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/2-plugin-workflows
# Run the OAuth example
deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/3-plugin-api-auth
# Run the manual dependencies example
deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/4-manual-deps
# Run the chunked storage demo
deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/chunked-storage-demo备注：示例可能需要环境配置(.env 文件）以实现完整功能。
✨ 主要特点
- 🎯 插件系统：自动发现和加载工作流和工具
- 🔐 OAuth就绪：内置OAuth提供者和可配置的第三方API消费者
- ⚡ 双重运输：带会话管理的STDIO和HTTP传输
- 💾 永久存储：基于Deno KV的存储，具有自动清理功能
- 📊 综合录井：全程审计跟踪和结构化日志记录
- 🔧 类型安全：完全支持TypeScript，具有严格的检查和验证
- 🧪 测试支持：广泛的测试工具和演示模式
- 📦 为JSR做好准备：发布在JSR注册表上，便于安装
⚙️ 配置概述
该库支持通过环境变量进行全面配置。以下是关键设置：
基本配置
# Transport type
MCP_TRANSPORT=stdio|http # Default: stdio
HTTP_PORT=3000 # Default: 3001
# Plugin discovery
PLUGINS_DISCOVERY_PATHS=./src/plugins
PLUGINS_AUTOLOAD=true
# Storage
STORAGE_DENO_KV_PATH=./data/app.db
# Logging
LOG_LEVEL=info # debug|info|warn|error
# MCP Server Instructions (for LLM context)
MCP_SERVER_INSTRUCTIONS="Custom instructions for LLM..."
MCP_INSTRUCTIONS_FILE=./path/to/instructions.mdOAuth集成
# OAuth Provider (when MCP server acts as OAuth provider)
OAUTH_PROVIDER_CLIENT_ID=your-client-id
OAUTH_PROVIDER_CLIENT_SECRET=your-client-secret
# OAuth Consumer (for third-party API integration)
OAUTH_CONSUMER_PROVIDER=example
OAUTH_CONSUMER_CLIENT_ID=third-party-client-id
OAUTH_CONSUMER_CLIENT_SECRET=third-party-secret📚 有关完整的配置详细信息，请参阅 示例 -每个都显示了不同的配置模式。
MCP服务器说明
MCP服务器说明为LLM了解服务器的功能、工具和工作流提供了必要的上下文。这些指令由服务器自动加载，并可供MCP客户端使用。
配置选项 （按优先顺序）：
- 直接配置:
MCP_SERVER_INSTRUCTIONS="Your instructions here..." - 文件路径:
MCP_INSTRUCTIONS_FILE="./path/to/instructions.md" - 默认文件：地点
mcp_server_instructions.md在项目根目录中 - 自动回退：库提供以工作流为中心的通用说明
为什么指令很重要:
- LLM背景：帮助AI模型了解服务器的特定功能
- 工具使用：就何时以及如何使用不同工具提供指导
- 工作流模式：解释复杂的多步骤流程和错误处理
- 认证：记录OAuth要求和安全注意事项
- 最佳实践：分享最佳使用模式和故障排除技巧
每 示例应用程序 包括显示不同复杂性级别和用例的定制说明。
🏗️ 架构概述
Beyond MCP Server提供了一个分层架构，将关注点分开：
核心组件
- 🚀 BeyondMcpServer：主服务器协调所有组件
- 🔄 传输层：带会话管理的STDIO/HTTP传输
- 🔌 插件系统：自动发现和加载工具/工作流
- 🔐 OAuth服务：身份验证流的提供者和使用者
- 💾 存储层：基于Deno KV的持久性，具有自动清理功能
- 📊 记录系统：带有审计跟踪的结构化日志记录
插件架构
- 工具：用于直接操作的简单、单一用途的功能
- 工作流：用于复杂业务逻辑的多步骤、有状态流程
- 插件：用于分发的捆绑工具和工作流程集合
🎯 设计目标：您专注于业务逻辑，库处理基础设施。
📚 文档与支持
面向图书馆用户（构建MCP服务器）
社区与支持
📄 许可证
MIT许可证-请参阅 许可证 了解详情。
🔗 相关项目
- 超越更好 - 推荐AI驱动的开发助手 用于构建MCP服务器。看 指南-create-app.md 了解集成细节。
- 模型上下文协议 -MCP TypeScript官方SDK
______________________________________________________________________
🛠️ 对于贡献者和维护者
*以下部分适用于对bb-mcp服务器库本身做出贡献或进行维护的人员。*
🚀 开发设置
# Clone the repository
git clone https://github.com/beyond-better/bb-mcp-server.git
cd bb-mcp-server
# Run all tests (library + examples)
deno task test:all
# Run library tests only
deno task test
# Run specific test file
deno task test tests/unit/storage/KVManager.test.ts
# Run with coverage
deno task tool:test🧪 测试
- 单元测试：覆盖率>90%的所有库组件
- 集成测试：端到端工作流执行，OAuth流
- 示例测试：每个示例应用程序中的演示测试
- 模拟服务：独立测试的全面模拟
📋 需求
- 德诺：版本2.5.0或更高版本
- 权限:
--allow-all --unstable-kv（适用于Deno KV操作） - 标准符合性：TypeScript严格模式，ESLint规则
🤝 贡献
该库正在积极开发中，并从生产MCP服务器中提取。欢迎投稿！
贡献指南
- 遵循新组件的既定模式
- 确保测试对新功能的覆盖率超过90%
- 保持与提取组件的向后兼容性
- 添加功能时更新文档和示例
- 使用TypeScript严格模式并遵循现有的代码风格
开发流程
- 分叉与克隆：分叉回购并克隆你的分叉
- 分支：从以下位置创建要素分支
main - 开发：按照既定模式进行更改
- 测试：运行
deno task test:all验证所有测试是否通过 - 文件：更新相关文件和示例
- 公关：提交带有清晰描述的拉取请求