MCP Typescript Sample

mcp类型脚本示例

带有身份验证的生产就绪MCP设置（客户端/服务器）的示例实现，使用现代ES模块在Typescript（节点）中完全实现。

\[！注意\] 为了演示，代理连接到由Ollama提供服务的本地托管LLM。请随意集成您选择的AI堆栈（请参阅 *客户端实现* 在......下面

______________________________________________________________________

设置/先决条件

在运行服务器或客户端之前，请确保您具备以下先决条件。

发展环境（当地）

1. Node.js （v18或更高版本）

- 从下载并安装 - 验证安装： node --version

1. 奥拉玛 （用于客户演示）

👉 请随意使用另一个LLM（在本地或云中运行，并调整下面的客户端实现）：

- 从以下位置安装Ollama 奥拉玛 - 拉动所需的模型： ollama pull qwen3:4b - 确保Ollama正在运行 http://localhost:11434

微软Entra ID

此参考实现需要一个配置了应用程序注册的Microsoft Entra ID租户：

1. Microsoft Entra ID应用程序注册

- 在Microsoft Entra ID中配置新的应用程序注册： - 具有自定义作用域的API权限 mcp:tools - 身份验证设置（用于客户端中的交互式登录） - 公开具有所需作用域的API

> \[！提示\] > 关于API范围：确保您通过在应用程序注册中公开web API来添加专用范围（如果需要任何指导，请单击此链接： ).

此信息将在客户端和服务器设置中使用：

• AZURE_TENANT_ID：您的Entra ID租户
• AZURE_CLIENT_ID：您的应用程序注册客户端ID
• AZURE_CLIENT_SECRET：您的应用程序注册客户端密码（用于服务器）
• AZURE_CLIENT_SCOPE：API范围（格式： api:///mcp:tools)

项目结构（建筑）

此monorepo包含两个主要组件：

• /server：使用Express.js、JWT身份验证和MCP SDK实现MCP服务器
• /client：通过AI SDK集成和交互式CLI实现MCP客户端

服务器

主要特点：

• JWT身份验证：使用JWKS验证Entra ID中的令牌
• 无状态模式：为每个请求创建新的传输，以防止ID冲突
• 安全API：验证作用域、颁发者和令牌签名
• Express.js：通过HTTP传输的JSON-RPC HTTP服务器

服务器体系结构：

server/
├── src/
│   ├── main.ts              # Express server setup
│   ├── auth/
│   │   └── validation.ts    # JWT validation middleware
│   ├── context/
│   │   └── AuthContext.ts   # Authentication context management
│   ├── mcp/
│   │   └── server.ts        # MCP server implementation
│   └── utils/
│       └── api-client.ts    # API client utilities

客户端

主要特点：

• 交互式身份验证：使用Entra ID交互式令牌请求流
• MCP客户端：使用HTTP传输连接到远程MCP服务器
• AI SDK集成：与Vercel AI SDK配合使用，用于LLM交互
• 流媒体响应：LLM响应的实时流式传输
• 工具调用：根据LLM请求自动调用MCP工具

客户端架构：

client/
├── src/
│   ├── main.ts                          # CLI application entry point
│   ├── bootstrap.ts                     # Environment configuration loader
│   ├── mcp/
│   │   └── client.ts                    # MCP client factory
│   └── utils/
│       └── TokenAcquisitionHelper.ts    # Entra ID token acquisition

通往卓越的捷径

服务器

MCP服务器通过HTTP传输提供对MCP工具的身份验证访问。

1.配置环境变量

导航到 server 目录并创建 .env 模板中的文件：

cd server
cp .env.template .env

编辑 .env 使用您的Entra ID凭据：

# Entra ID Configuration for OAuth2/MSAL
AZURE_TENANT_ID=your-tenant-id-here
AZURE_CLIENT_ID=your-client-id-here
AZURE_CLIENT_SECRET=your-client-secret-here

# MCP Server Configuration
REMOTE_MCP_SERVER_PORT=3000

2.安装依赖项

npm install

3.运行服务器

在开发模式下启动服务器，并自动重新加载：

npm start

或者在生产模式下构建和运行：

npm run build
node dist/main.js server

4.验证服务器

服务器应在上运行 http://localhost:3000/mcp。您应该看到：

MCP Server running on http://localhost:3000/mcp

______________________________________________________________________

客户端

MCP客户端演示了如何使用MCP工具连接到MCP服务器、获取身份验证令牌以及与LLM交互。

1.配置客户端环境变量

导航到 client 目录并创建 .env.development 模板中的文件：

cd client
cp .env.template .env.development

编辑 .env.development 根据您的配置：

# Entra ID Configuration for OAuth2/MSAL
AZURE_TENANT_ID=your-tenant-id-here
AZURE_CLIENT_ID=your-client-id-here
AZURE_CLIENT_SCOPE=api://your-client-id-here/mcp:tools

REMOTE_MCP_SERVER_BASE_URL=http://localhost:3000/mcp

2.安装客户端依赖项

npm install

3.确保先决条件

在运行客户端之前：

• ✅ MCP服务器正在运行 （见上文：服务器>运行服务器）

• ✅ Ollama 正在运行 使用所需型号：

  ollama serve
  ollama pull qwen3:4b

4.运行客户端

启动交互式CLI应用程序：

npm start

5.身份验证和交互

1. 应用程序将提示您使用Entra ID进行身份验证（交互式浏览器登录）
2. 成功验证后，您将看到已注册的MCP工具
3. 在交互式提示中开始提问

交互示例：

🧠 Simple console application
Acquiring an access token from Entra ID... ✅ ok
Registered MCP Server tools: ['tool1', 'tool2', ...]

Starting the command line prompting game.
Have fun! 😃 Type 'exit' or 'quit' to terminate.
Ask: How many users work in my company?
AI's response:
[Streaming response from LLM using MCP tools...]

切换到其他AI提供商

客户端包括Ollama和OpenAI的示例。要改用OpenAI：

1. 在中取消对OpenAI示例的注释 client/src/main.ts
2. 设置您的OpenAI API密钥： export OPENAI_API_KEY=your-key
3. 替换 streamText 电话与 generateText 呼叫

故障排除

服务器问题

• 端口已在使用中：更改 REMOTE_MCP_SERVER_PORT 在 .env 或终止已运行的服务器
• 令牌验证失败：验证Entra ID应用程序注册配置
• JWKS错误：检查您的应用程序注册是否具有正确的签名密钥

客户问题

• 认证失败：确保Entra ID应用程序配置了正确的重定向URI
• 无法连接到服务器：验证 REMOTE_MCP_SERVER_BASE_URL 并且该服务器正在运行
• 奥拉马·埃罗尔斯：确保Olama正在运行(ollama serve)模型被拉取

常见问题

• 模块分辨率错误：确保您使用的是支持ES模块的Node.js v22+
• TypeScript错误：运行 npm run type-check 验证TypeScript配置
• 网络错误：检查防火墙设置和本地主机连接

附加信息

开发脚本

服务器和客户端都支持以下npm脚本：

• npm start：以开发模式运行
• npm run build：将TypeScript编译为JavaScript
• npm run type-check：检查TypeScript类型而不发出文件

安全考虑

• 永不承诺 .env 文件：这些文件包含敏感凭据
• 令牌验证：服务器使用Entra ID中的JWKS验证令牌
• 范围检查：确保 mcp:tools 范围配置正确
• 生产部署：使用适当的密钥管理（Azure密钥库、环境变量等）

了解更多

• 模型上下文协议文档
• Vercel AI SDK
• Ollama文件