@tscodex/mcp服务器示例

MCP（模型上下文协议）服务器示例，演示NewsAPI的新闻标题和文章。使用TypeScript和 @tscodex/mcp-sdk 用于快速MCP服务器开发。

建立在 @tscodex/mcp-sdk -该项目使用官方的TSCodex MCP SDK进行服务器基础设施、身份验证、配置管理和协议处理。

______________________________________________________________________

🚀 快速链接

用于管理MCP服务器的桌面应用程序|VS代码/光标扩展桥

______________________________________________________________________

🎯 这是什么？

这是一个 MCP服务器示例 建立在 @tscodex/mcp-sdk 展示了创建MCP服务器的最佳实践。它使用NewsAPI提供新闻搜索功能，可以通过两种方式工作：

单独模式：直接通过运行 npx 或 npm，传递环境变量和配置

管理模式：与一起使用 MCP经理 用于工作空间隔离、可视化配置以及与Cursor的无缝集成

关于TSCodex

TSCodex 是一个用于构建与LLM配合使用的工具的项目。这个生态系统中的第一个工具是 MCP经理 -流程管理器，其：

管理MCP服务器进程：控制服务器生命周期、监视运行状况并处理重启
提供可视化界面：使用React Flow构建的漂亮UI，用于可视化和管理您的MCP基础设施
启用工作区隔离：创建工作区代理，以便一台服务器可以为多个Cursor项目提供服务
安全地管理秘密：三级秘密覆盖系统（全局→ 工作区→ 服务器），带操作系统钥匙链存储
处理身份验证：所有服务器的集中身份验证管理
AI代理集成：注册OpenAI兼容的API并将其代理到服务器，而不暴露密钥
动态MCP工具：通过具有人工智能表单生成功能的特殊MCP服务器动态创建工具和资源

这 @tscodex/mcp-sdk 是构建基于HTTP的MCP服务器的快速、类型安全的SDK的基础。它不需要MCP Manager，可以独立运行，但MCP Manager在其上添加了强大的管理功能。

架构概述

┌─────────────────────────────────────────────────────────────┐
│                    Cursor (IDE Editor)                      │
│  ┌───────────────────────────────────────────────────────┐  │
│  │         MCP Manager Bridge Extension                  │  │
│  │  - Auto-registers workspace                           │  │
│  │  - Syncs with MCP Manager                             │  │
│  │  - Updates Cursor mcp.json                            │  │
│  └───────────────────────────────────────────────────────┘  │
│                         │                                    │
│              HTTP API + WebSocket                            │
│                         │                                    │
└─────────────────────────┼────────────────────────────────────┘
                          │
┌─────────────────────────┼────────────────────────────────────┐
│              MCP Manager (Desktop App)                        │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  - Process Management                                  │  │
│  │  - Workspace Isolation (Proxy)                        │  │
│  │  - Visual Configuration UI                            │  │
│  │  - Secrets Management (3-level override)              │  │
│  │  - Permissions System                                 │  │
│  │  - AI Agent Proxy                                     │  │
│  │  - MCP Tools (Dynamic Server)                         │  │
│  └───────────────────────────────────────────────────────┘  │
│                         │                                    │
│         ┌────────────────┴────────────────┐                  │
│         │                                 │                  │
│  ┌──────▼──────┐                  ┌──────▼──────┐          │
│  │ MCP Tools   │                  │ MCP Servers │          │
│  │ (Dynamic)   │                  │ (e.g. this) │          │
│  └──────┬──────┘                  └──────┬──────┘          │
│         │                                 │                  │
└─────────┼─────────────────────────────────┼──────────────────┘
          │                                 │
          └────────────┬────────────────────┘
                       │
          ┌────────────▼────────────┐
          │  @tscodex/mcp-sdk       │
          │  (Core SDK)              │
          └─────────────────────────┘

运作原理

问题：实际项目要求每个Cursor工作区使用自己的工作区上下文。例如，新闻服务器可能需要当前项目的根路径来保存文章或缓存数据。但是，您不能为每个项目运行单独的服务器实例。

解决方案: MCP经理 允许您：

跑 一个服务器实例 （例如。， @tscodex/mcp-server-example)
创建 多个工作区代理 使用工作区上下文转发请求
SDK从当前工作区接收标头，并允许一个服务器处理不同的工作区

桥: MCP经理桥 自动：

按项目路径在MCP管理器中注册工作区
将游标与管理器同步
在本地注册代理MCP服务器 mcp.json
在工作空间之间提供完美的封装和连接

______________________________________________________________________

🎨 特性

📰 新闻搜索：按主题搜索新闻，按国家/类别获取头条新闻
🌍 新闻来源：列出NewsAPI的可用新闻来源
👋 个性化问候：使用会话信息问候用户
🤖 人工智能集成：演示AI Agent集成的示例工具
📝 提示模板：用于常见任务的预构建提示模板
🔒 认证：基于会话的身份验证，支持角色
⚙️ 类型安全配置：使用TypeBox进行基于JSON模式的配置
🔐 秘密管理：通过安全的API密钥处理 SECRET_* 前缀

______________________________________________________________________

📦 安装

选项1：独立（通过npx）

npx @tscodex/mcp-server-example@latest

选项2：全局安装

npm install -g @tscodex/mcp-server-example

选项3：管理模式（推荐）

与一起使用 MCP经理 为了获得最佳体验：

安装MCP管理器：从下载

安装桥架延伸部分: MCP经理桥来自VS代码市场

添加服务器：在MCP管理器中，添加 @tscodex/mcp-server-example 作为新服务器

配置：使用可视化UI配置服务器（基于JSON模式）

启用：在Cursor中为您的工作区启用服务器

管理模式的好处：

✅ 可视化配置：无需手动编辑JSON文件
✅ 工作区隔离：每个项目都有自己的工作区代理
✅ 安全的秘密：3级秘密覆盖（全局→ 工作区→ 服务器）
✅ 权限控制：对每个服务器可以访问的内容进行精细控制
✅ AI代理集成：在不向服务器公开API密钥的情况下使用AI代理
✅ 令牌统计：透明地跟踪AI使用情况
✅ 自动同步：网桥自动与光标同步

______________________________________________________________________

🚀 快速开始

单独模式

# Start server with default settings
npx @tscodex/mcp-server-example@latest

# Server will start on port 3000 by default (host: 0.0.0.0)
# MCP endpoint: http://localhost:3000/mcp

# With custom host and port
npx @tscodex/mcp-server-example@latest --host 127.0.0.1 --port 3000

# With project root (REQUIRED for standalone mode)
npx @tscodex/mcp-server-example@latest --host 127.0.0.1 --port 3000 --root /path/to/project

# Get server metadata (for MCP Manager integration)
npx @tscodex/mcp-server-example@latest --meta

管理模式

启动MCP管理器 桌面应用程序

打开的游标 与您的项目

桥楼伸展平台 自动：

- 注册您的工作区 - 连接到MCP管理器 - 将已启用的服务器同步到Cursor的 mcp.json

启用服务器：单击播放图标 @tscodex/mcp-server-example 在桥接面板中

配置：使用MCP管理器UI配置服务器（如果需要）

______________________________________________________________________

⚙️ 配置

配置文件

创建 .mcp-server-example.json 在项目根目录中：

{
  "greeting": "Hello",
  "maxItems": 10
}

配置选项：

greeting （字符串，可选，默认值： "Hello")：默认问候语
maxItems （数字，可选，默认值： 10)：要返回的最大新闻项数（1-100）

配置源

SDK从多个源加载配置，优先级如下：

扩展配置 (MCP_CONFIG env var）-最高优先级
CLI参数 (--key value 格式）
环境变量 （转换自 ENV_VAR_NAME 到 camelCase)
配置文件 (.mcp-server-example.json)
架构默认值 -最低优先级

秘密管理

⚠️ 安全说明： API密钥存储为秘密（环境变量 SECRET_ 前缀）而不是在配置文件中。

在独立模式下：

export SECRET_NEWSAPI_KEY=your_newsapi_key

在管理模式下：

MCP管理器提供 三级秘密覆盖系统:

全球：所有服务器都有秘密
工作区：特定于工作空间的秘密
服务器：特定于服务器实例的秘密

这允许对每个服务器可以访问的秘密进行细粒度控制。

获取API密钥：

新闻API: https://newsapi.org/register（提供免费套餐）

______________________________________________________________________

🔒 安全和权限

安全功能

MCP经理 提供企业级安全：

OS钥匙链存储：秘密存储在操作系统的安全密钥链中（Windows凭据管理器、macOS密钥链、Linux特勤局）

无关键风险：API密钥从不直接传递给MCP服务器。需要AI访问的服务器使用AI代理代理机制

进程隔离：每台服务器都在自己的进程中运行，环境隔离

权限系统：对每个服务器可以访问的内容进行精细控制

工作区范围界定：文件系统访问权限始终仅限于项目根目录-服务器无法访问工作区之外的文件

权限系统

MCP Manager的权限系统允许您配置：

环境变量：服务器可以使用哪些环境变量
秘密访问：服务器可以访问哪些机密（3级覆盖：全局→ 工作区→ 服务器）
AI代理访问：服务器是否可以使用AI Agent代理，允许使用哪些模型
文件系统访问：工作区根访问权限（始终限于项目，无法访问父目录）

权限配置示例：

{
  "envVars": ["NODE_ENV", "DEBUG"],
  "secrets": ["SECRET_NEWSAPI_KEY"],
  "aiAgent": {
    "enabled": true,
    "allowedModels": ["gpt-4", "gpt-3.5-turbo"]
  }
}

MCP管理器主要功能

MCP经理 是一个全面的桌面应用程序，提供：

1. 可视化服务器管理

基于React Flow的漂亮界面，可可视化您的MCP基础设施
一目了然地查看所有服务器、工作区及其连接
用于管理服务器配置的拖放界面

2. 服务器发现和元数据

从MCP服务器自动发现工具、资源和提示
显示服务器配置的JSON架构
基于模式的可视化配置编辑器-无需手动JSON编辑

3. 工作区隔离

为每个Cursor项目创建工作区代理
一个服务器实例可以服务于多个工作区
每个工作区都有自己的隔离上下文和项目根
SDK自动接收工作区标头并调整行为

4. 三级秘密覆盖系统

Global Secrets (All Servers)
    ↓
Workspace Secrets (All Servers in Workspace)
    ↓
Server-Specific Secrets (Only This Server)

对秘密访问的细粒度控制
秘密安全地存储在操作系统钥匙链中
从未在日志或配置文件中公开

5. AI代理

注册与OpenAI兼容的API（任何baseUrl+API密钥）
代理AI向服务器发出请求，而不暴露密钥
透明地跟踪令牌使用情况
每台服务器基于权限的访问控制
成本监控和统计

6. 动态MCP工具服务器

允许动态创建工具和资源的特殊MCP服务器
人工智能驱动的表单生成-描述您的需求，人工智能填写表单
非常适合快速原型制作和定制工具创建
与AI Agent集成，实现智能工具生成

7. 流程管理

一键启动、停止、重启服务器
健康监测和自动恢复
实时日志和状态更新
资源使用情况跟踪

8. 通过桥接进行光标集成

按项目路径自动注册工作区
Cursor和MCP管理器之间的实时同步
自动 mcp.json Cursor中的更新
每个工作区无缝启用/禁用服务器

______________________________________________________________________

🤖 AI代理集成

MCP管理器包括一个内置 AI 代理 即：

注册与OpenAI兼容的API：通过配置 baseUrl 和API密钥
提供代理：服务器可以在不直接访问API密钥的情况下使用AI
令牌统计：透明地跟踪所有AI使用情况
基于权限的：每台服务器必须在权限中启用AI代理访问

工作原理：

注册AI提供商 在MCP管理器中：

- 基本URL: https://api.openai.com/v1 - API密钥：（安全存储在操作系统密钥链中） - 型号： gpt-4, gpt-3.5-turbo等等。

为服务器启用：在服务器权限中，启用AI代理访问

在服务器中使用：SDK提供了访问AI代理的方法：

   const aiResponse = await server.getAiAgent().chat({
     model: 'gpt-4',
     messages: [{ role: 'user', content: 'Generate news summary' }]
   });

轨道使用情况：所有令牌使用情况都会在MCP管理器中跟踪和显示

优点：

✅ 没有API密钥暴露给服务器
✅ 集中式人工智能使用跟踪
✅ 易于切换的AI提供商
✅ 成本监控

______________________________________________________________________

🛠️ 可用工具

新闻工具

get_news -从NewsAPI获取新闻头条。支持按国家/类别或按查询搜索头条新闻

- 论据： query （可选）， country （可选）， category （可选）， pageSize （可选，1-100，默认值：10）

问候工具

greet -使用会话信息（电子邮件、全名）问候当前用户

- 论据： formal （布尔值，可选）：使用正式问候风格（默认值：false）

AI演示工具

ai_demo_chat -演示AI Agent集成的示例工具

- 演示如何从MCP管理器中使用AI代理代理

______________________________________________________________________

📚 资源

`newsapi://sources`

返回NewsAPI中可用新闻源的列表，包括其类别、国家和语言。

______________________________________________________________________

📝 提示

`get_news_about`

获取特定主题新闻的模板。

论据：

topic （字符串，必填）：搜索新闻的主题（例如，“人工智能”、“气候变化”）

`greet_current_user`

用于问候当前登录用户的模板。自动使用会话数据。

______________________________________________________________________

📚 示例用法

示例1：获取头条新闻

# Tool: get_news
# Country: us
# Category: technology
# Page Size: 5

示例2：搜索新闻

# Tool: get_news
# Query: "artificial intelligence"
# Page Size: 10

示例3：问候用户

# Tool: greet
# Formal: false

______________________________________________________________________

🔧 环境变量

所有环境变量都是可选的，具有合理的默认值：

# Server settings
MCP_PORT=3000              # Server port (default: 3000)
MCP_HOST=0.0.0.0          # Server host (default: 0.0.0.0)
MCP_PATH=/mcp             # MCP endpoint path (default: /mcp)
MCP_PROJECT_ROOT=/path     # Project root directory

# Configuration (alternative to config file)
GREETING=Hello
MAX_ITEMS=10

# API Keys (required for news tools)
SECRET_NEWSAPI_KEY=your_key

______________________________________________________________________

🏗️ 基于@tscodex/mcp-sdk构建

该项目建立在 @tscodex/mcp-sdk，它提供：

✅ MCP服务器基础架构：HTTP传输、协议处理、请求路由
✅ 身份验证和会话管理：安全会话处理
✅ 配置加载：CLI参数、环境变量、具有优先级系统的配置文件
✅ 秘密管理: SECRET_* 环境变量处理
✅ 工作区上下文：自动工作区根检测和标头处理
✅ AI代理集成：内置对AI代理代理的支持
✅ 类型安全：TypeBox模式完全支持TypeScript

SDK的主要功能：

基于HTTP的快速MCP服务器创建
无需数据库-无状态设计
使用或不使用MCP Manager
从标题自动生成工作区上下文
基于JSON模式的配置

______________________________________________________________________

🧪 发展

# Clone repository
git clone https://github.com/unbywyd/tscodex-mcp-server-example.git
cd tscodex-mcp-server-example

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run production build
npm start

# Get metadata (for MCP Manager)
npm run meta

______________________________________________________________________

📁 项目结构

mcp-server-example/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # Server setup
│   ├── config.ts             # Configuration schema
│   ├── config-loader.ts      # Config loading logic
│   ├── utils.ts              # Utility functions
│   └── tools/                # MCP tools
│       ├── greeting.ts       # Greeting tools
│       ├── news.ts           # News API tools
│       ├── news-resources.ts # News resources
│       ├── news-prompts.ts   # News prompts
│       └── ai-demo.ts        # AI demo tools
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
├── example-config.json       # Example configuration
└── README.md

______________________________________________________________________

📋 需求

Node.js>=18.0.0
NewsAPI密钥（可选，但新闻工具需要）-在以下网址获取免费密钥https://newsapi.org/register

______________________________________________________________________

🖥️ 平台支持

视窗: ✅ 完全支持-提供带有代码签名的预构建二进制文件

macOS: ⚠️ 需要代码签名-该项目主要是为Windows构建的。macOS需要代码签名才能分发。开发人员可以使用存储库中的可用资源构建和签署自己的二进制文件。 如果您想在macOS支持方面进行合作或具有代码签名功能，请联系作者。

Linux: ✅ 完全支持-提供预构建的二进制文件

备注：MCP管理器目前主要为Windows构建。macOS支持需要代码签名证书。对于想要构建和签署自己的macOS二进制文件的开发人员，存储库中提供了所有源代码和构建资源。如果您有兴趣在macOS支持方面进行合作，请联系我们！

______________________________________________________________________

🔗 相关项目

MCP经理 -用于MCP服务器管理的桌面应用程序
MCP经理桥 -VS代码/光标扩展桥
@tscodex/mcp-sdk -用于构建MCP服务器的SDK
@tscodex/mcp图像 -图像处理MCP服务器
MCP服务器示例（本项目） -MCP服务器示例

______________________________________________________________________

📄 许可证

麻省理工学院

______________________________________________________________________

👤 作者

生命

网站: tscodex.com

______________________________________________________________________

🔗 链接

网站: https://tscodex.com
GitHub: https://github.com/unbywyd/tscodex-mcp-server-example
NPM: https://www.npmjs.com/package/@tscodex/mcp服务器示例
问题: https://github.com/unbywyd/tscodex-mcp-server-example/issues
MCP-SDK: https://www.npmjs.com/package/@tscodex/mcp-sdk
MCP SDK GitHub: https://github.com/unbywyd/tscodex-mcp-sdk
MCP经理: https://github.com/unbywyd/tscodex-mcp-manager-app
MCP电桥: https://github.com/unbywyd/tscodex-mcp-manager-bridge

Tscodex MCP Example

快速接入

详细介绍

@tscodex/mcp服务器示例

🚀 快速链接

🎯 这是什么？

关于TSCodex

架构概述

运作原理

🎨 特性

📦 安装

选项1：独立（通过npx）

选项2：全局安装

选项3：管理模式（推荐）

🚀 快速开始

单独模式

管理模式

⚙️ 配置

配置文件

配置源

秘密管理

🔒 安全和权限

安全功能

权限系统

MCP管理器主要功能

1. 可视化服务器管理

2. 服务器发现和元数据

3. 工作区隔离

4. 三级秘密覆盖系统

5. AI代理

6. 动态MCP工具服务器

7. 流程管理

8. 通过桥接进行光标集成

🤖 AI代理集成

🛠️ 可用工具

新闻工具

问候工具

AI演示工具

📚 资源

newsapi://sources

📝 提示

get_news_about

greet_current_user

📚 示例用法

示例1：获取头条新闻

示例2：搜索新闻

示例3：问候用户

🔧 环境变量

🏗️ 基于@tscodex/mcp-sdk构建

🧪 发展

📁 项目结构

📋 需求

🖥️ 平台支持

🔗 相关项目

📄 许可证

👤 作者

🔗 链接

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`newsapi://sources`

`get_news_about`

`greet_current_user`