STARWARCLOUD STARWAR.AI
返回市场
系统提示-mcp服务器

系统提示-mcp服务器

作者：systempromptio90 星标更新：2025-07-03
安装使用来源：spider==github.com

项目介绍

systemprompt-mcp-server

npm 版本 许可证: MIT Twitter 关注 Discord

网站 | 文档

由 systemprompt.io 赞助

此 MCP 服务器实现是由 systemprompt.io 赞助的——他们创建了世界上第一个原生移动 MCP 客户端，适用于 iOS 和 Android，并完全免费开源提供给社区。

如果您发现这个项目有用，请考虑：

  • ⭐ 在该仓库上加星
  • 👍 在我们的社交渠道上点赞/关注
  • 🔗 与您的网络分享

您的支持有助于我们继续为 AI 社区创造有价值的开源工具！

🚀 了解更多：要了解此实现的交互式演示并进行实时 SDK 测试，请访问 systemprompt.io/mcp-server

这是一个生产就绪的模型上下文协议（MCP）服务器，展示了完整的 MCP 规范，包括 OAuth 2.1、采样、激发、结构化数据验证和实时通知。

此实现使用 Reddit 作为现实世界的示例来展示 OAuth 2.1 流程和高级 MCP 功能，但架构设计易于适应任何需要 OAuth 认证的 API。

此服务器可与任何支持高级功能（如采样和通知）的 MCP 兼容客户端一起工作。

🔍 MCP Inspector 兼容

此服务器完全兼容MCP Inspector，提供对以下内容的支持：

  • ✅ OAuth 2.1 认证 - 完整流程，包括 PKCE
  • ✅ 工具 - 所有 Reddit 互动能力
  • ✅ 提示 - 动态内容生成提示
  • ✅ 采样 - 带有人工审批的 AI 辅助内容
  • ✅ 通知 - 实时进度更新

自行测试：npm run inspector

🌟 此实现为何重要

使用 Reddit 展示 OAuth 2.1

此实现使用Reddit 的 API 作为现实世界的示例来展示如何在 MCP 服务器中构建完整的 OAuth 2.1 流程。选择 Reddit 是因为：

  • 大多数操作都需要 OAuth 认证
  • 提供丰富的 API 来展示各种 MCP 功能
  • 是一个文档齐全且公开访问的 API
  • 展示了实际的认证挑战和解决方案

注意：虽然此服务器使用 Reddit，但 OAuth 实现和架构模式设计为易于适应任何基于 OAuth 的 API（如 GitHub、Google、Slack 等）。

展示的关键特性

此存储库作为 MCP 服务器实现的黄金标准，展示了：

  • 完整的 MCP 规范覆盖：从 OAuth 到采样的每个功能都已实现
  • 生产架构：内置多用户会话、安全性和可扩展性
  • 开发者体验：干净的代码结构，适合学习或分叉
  • 真实的 OAuth 集成：完整的 OAuth 2.1 流程，包括 PKCE、JWT 令牌和会话管理
  • AI 原生设计：深度集成 LLM 用于内容生成和分析

📚 目录

✨ 特性

核心 MCP 实现

  • 🔐 OAuth 2.1 流程：完整的 8 步实现，包括 PKCE 和 JWT
  • 🛠️ 工具系统：全面的 Reddit 互动工具
  • 📚 资源及提示：动态提示生成和资源管理
  • 🤖 采样：带有人工监督的 AI 辅助内容生成
  • 💬 激发：工具执行期间的动态用户输入收集
  • ✅ 结构化数据：所有输入/输出的 JSON Schema 验证
  • 📡 通知：实时进度更新和状态通知
  • 🔄 会话管理：多用户支持，自动清理

Reddit 集成功能

  • 内容发现：搜索和分析 Reddit 内容
  • 用户互动：查看消息、通知和管理账户
  • 子版块信息：检索子版块详情和帖子
  • 评论线程：浏览和分析 Reddit 讨论

开发者功能

  • TypeScript：完整的类型安全性，带有全面的接口
  • 模块化架构：清晰的责任分离
  • 错误处理：强大的错误管理，带有自定义错误类型
  • Docker 支持：准备好容器化部署
  • 测试：包含示例测试实现
  • 文档：广泛的内联文档和示例

🚀 快速开始

🐳 最简单的安装（Docker 与 npx）

立即使用 Docker 运行服务器——无需安装：

第一步：创建 Reddit 应用及初始配置

  1. 在 reddit.com/prefs/apps 创建 Reddit 应用

    • 选择“脚本”类型
    • 设置重定向 URI：http://localhost:3000/oauth/reddit/callback

  2. 创建初始 .env 文件：

cat > .env << EOF
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret
JWT_SECRET=any_random_string_here
EOF

第二步：运行服务器

# 使用 Docker 运行（自动拉取镜像）
docker run -it --rm \
  -p 3000:3000 \
  --env-file .env \
  --name mcp-reddit \
  node:20-slim \
  npx @systemprompt/systemprompt-mcp-server

第三步：完成 OAuth 认证

  1. 在您的 MCP 客户端中连接到 http://localhost:3000
  2. OAuth 流程将自动启动
  3. 在浏览器中授权应用
  4. 复制返回的 OAuth 令牌

第四步：更新环境变量以包含令牌

# 停止容器（Ctrl+C）

# 将 OAuth 令牌添加到您的 .env 文件中
echo "OAUTH_ACCESS_TOKEN=your_oauth_token_here" >> .env

# 使用令牌重新启动
docker run -it --rm \
  -p 3000:3000 \
  --env-file .env \
  node:20-slim \
  npx @systemprompt/systemprompt-mcp-server

现在您可以使用经过身份验证的会话使用所有 Reddit 工具！

安装

# 通过 npm
npm install -g @systemprompt/systemprompt-mcp-server

# 通过 npx（无需安装）
npx @systemprompt/systemprompt-mcp-server

# 克隆以进行开发
git clone https://github.com/systempromptio/systemprompt-mcp-server.git
cd systemprompt-mcp-server
npm install
npm run build

配置

  1. 创建 Reddit 应用：reddit.com/prefs/apps

    • 选择“脚本”类型
    • 设置重定向 URI：http://localhost:3000/oauth/reddit/callback

  2. 设置环境变量：

在项目根目录创建一个 .env 文件：

# Reddit API 所需
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret
JWT_SECRET=your_jwt_secret       # JWT 签名密钥

# 可选
PORT=3000                        # 服务器端口（默认：3000）
OAUTH_ISSUER=http://localhost:3000  # OAuth 发行者 URL
REDIRECT_URL=http://localhost:3000/oauth/reddit/callback  # OAuth 重定向
REDDIT_USER_AGENT=linux:systemprompt-mcp-reddit:v2.0.0   # Reddit 用户代理
REDDIT_USERNAME=your_reddit_username  # 您的 Reddit 用户名（可选）
LOG_LEVEL=debug                  # 日志级别（debug, info, warn, error）

注意：环境变量对于本地开发和 Docker 部署都是必需的。

运行服务器

# 构建 TypeScript 代码
npm run build

# 运行构建的服务器
node build/index.js

# 开发模式下的监视模式
npm run watch
# 在另一个终端中：
node build/index.js

# 使用 Docker
npm run docker

🏗️ 架构

此实现遵循干净架构原则，各层之间有明确的分离：

┌─────────────────────────────────────────────────────────┐
│                    客户端应用程序                    │
│                  (systemprompt.io)                      │
└────────────────────────┬────────────────────────────────┘
                         │ MCP 协议
┌────────────────────────┴────────────────────────────────┐
│                    MCP 服务器层                      │
│  ┌─────────────┐  ┌─────────────┐  ┌────────────────┐  │
│  │   OAuth 2.1 │  │   会话   │  │  通知    │  │
│  │   处理程序   │  │   管理器   │  │    管理器     │  │
│  └─────────────┘  └─────────────┘  └────────────────┘  │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────┐
│                   处理程序层                          │
│  ┌─────────────┐  ┌─────────────┐  ┌────────────────┐  │
│  │    工具    │  │  资源  │  │    采样    │  │
│  │   处理程序   │  │   处理程序   │  │    处理程序     │  │
│  └─────────────┘  └─────────────┘  └────────────────┘  │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────┐
│                   服务层                          │
│  ┌─────────────┐  ┌─────────────┐  ┌────────────────┐  │
│  │   Reddit    │  │    认证     │  │     获取      │  │
│  │   服务   │  │   服务   │  │    服务     │  │
│  └─────────────┘  └─────────────┘  └────────────────┘  │
└─────────────────────────────────────────────────────────┘

关键组件

  • src/server.ts：主要 HTTP 服务器设置和 Express 配置
  • src/server/：核心服务器基础设施（MCP、OAuth、认证管理）
  • src/handlers/：工具、提示、资源和采样的请求处理程序
  • src/services/：业务逻辑和 Reddit API 集成
  • src/constants/：工具定义、服务器配置和模式
  • src/types/：TypeScript 类型定义和接口

🔐 OAuth 实现

此服务器实现了完整的 MCP OAuth 2.1 规范：

OAuth 流程步骤

  1. 初始 401 响应（src/server/oauth.ts）

    WWW-Authenticate: Bearer realm="MCP Reddit 服务器"

  2. 资源元数据（src/server/oauth.ts）

    {
  "authorization_server": "http://localhost:3000/.well-known/oauth"
}

  3. 授权服务器元数据（src/server/oauth.ts）

    • 令牌端点配置
    • PKCE 支持声明
    • 支持的授权类型

  4. 授权请求（src/server/oauth.ts）

    • PKCE 代码挑战
    • CSRF 保护的状态参数
    • Reddit OAuth 重定向处理

  5. Reddit OAuth 回调（src/server/oauth.ts）

    • Reddit 授权处理
    • 安全的状态验证

  6. 令牌交换（src/server/oauth.ts）

    • PKCE 验证
    • JWT 令牌生成
    • Reddit 凭据嵌入

  7. 认证请求（src/server/middleware.ts）

    • JWT 验证
    • 会话管理
    • 请求上下文注入

安全特性

  • PKCE 实现：防止授权码拦截
  • JWT 令牌：安全凭据存储和传输
  • 会话隔离：每个用户都有独立的 Reddit 凭据
  • 自动清理：会话在不活动后过期

🛠️ 工具参考

内容发现工具

search_reddit

跨 Reddit 搜索，带过滤器（src/handlers/tools/search-reddit.ts）

{
  "query": "typescript MCP",
  "subreddit": "编程",      // 可选特定子版块
  "sort": "相关性",
  "时间": "周",
  "限制": 10
}

get_post

获取特定帖子及其评论（src/handlers/tools/get-post.ts）

{
  "id": "post_id_here"             // Reddit 帖子 ID
}

get_channel

获取子版块帖子（src/handlers/tools/get-channel.ts）

{
  "subreddit": "编程",
  "sort": "热门"                    // "热门", "新", 或 "争议"
}

用户互动工具

get_notifications

获取用户通知和消息（src/handlers/tools/get-notifications.ts）

{
  "filter": "未读",              // "全部", "未读", "消息", "评论", "提及"
  "限制": 25,
  "markRead": false
}

get_comment

获取特定评论（src/handlers/tools/get-comment.ts）

{
  "id": "comment_id_here",
  "includeThread": true            // 包含完整的评论线程
}

示例和开发工具

elicitation_example

演示用户输入收集（src/handlers/tools/elicitation-example.ts）

{
  "type": "输入",                 // "输入", "确认", "选项"
  "prompt": "输入您的选择",
  "options": ["选项1", "选项2"] // 对于选项类型
}

sampling_example

演示 AI 辅助内容生成（src/handlers/tools/sampling-example.ts）

{
  "prompt": "生成一个代码示例",
  "maxTokens": 1_000,
  "temperature": 0.7
}

structured_data_example

演示结构化数据处理（src/handlers/tools/structured-data-example.ts）

{
  "format": "json",               // "json", "表格", "markdown"
  "data": { "key": "value" }
}

validation_example

演示输入验证（src/handlers/tools/validation-example.ts）

{
  "test_string": "示例",
  "test_number": 42,
  "test_enum": "选项1"
}

mcp_logging

请求服务器记录消息（src/handlers/tools/logging.ts）

{
  "level": "info",                // "debug", "info", "警告", "错误"
  "message": "调试消息",
  "data": { "附加": "上下文" }
}

🎯 高级特性

采样（AI 辅助内容生成）

采样实现（src/handlers/sampling.ts）遵循完整的 MCP 规范：

// 1. 客户端请求 AI 协助
await client.callTool("sampling_example", { 
  prompt: "分析这个子版块并提出行动建议",
  maxTokens: 1000,
  temperature: 0.7
});

// 2. 服务器启动