mcp类型脚本示例
带有身份验证的生产就绪MCP设置(客户端/服务器)的示例实现,使用现代ES模块在Typescript(节点)中完全实现。
> [!注意]
> 为了演示,代理连接到由Ollama提供服务的本地托管LLM。请随意集成您选择的AI堆栈(请参阅 客户端实现 在......下面
设置/先决条件
在运行服务器或客户端之前,请确保您具备以下先决条件。
发展环境(当地)
- Node.js (v18或更高版本)
- 从下载并安装 nodejs.org
- 验证安装:
node --version
- 奥拉玛 (用于客户演示)
👉 请随意使用另一个LLM(在本地或云中运行,并调整下面的客户端实现):
- 从以下位置安装Ollama 奥拉玛
- 拉动所需的模型:
ollama pull qwen3:4b - 确保Ollama正在运行
http://localhost:11434
微软Entra ID
此参考实现需要一个配置了应用程序注册的Microsoft Entra ID租户:
- Microsoft Entra ID应用程序注册
- 在Microsoft Entra ID中配置新的应用程序注册:
- 具有自定义作用域的API权限
mcp:tools - 身份验证设置(用于客户端中的交互式登录)
- 公开具有所需作用域的API
> [!提示]
> 关于API范围:确保您通过在应用程序注册中公开web API来添加专用范围(如果需要任何指导,请单击此链接: ).
此信息将在客户端和服务器设置中使用:
AZURE_TENANT_ID:您的Entra ID租户AZURE_CLIENT_ID:您的应用程序注册客户端IDAZURE_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服务器
服务器体系结构:```text
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工具
**客户端架构:**```text
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 模板中的文件:```bash
cd server
cp .env.template .env
编辑 `.env` 使用您的Entra ID凭据:```bash
# 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.安装依赖项```bash
npm install
#### 3.运行服务器
在开发模式下启动服务器,并自动重新加载:```bash
npm start
或者在生产模式下构建和运行:```bash
npm run build
node dist/main.js server
#### 4.验证服务器
服务器应在上运行 `http://localhost:3000/mcp`。您应该看到:```text
MCP Server running on http://localhost:3000/mcp
客户端
MCP客户端演示了如何使用MCP工具连接到MCP服务器、获取身份验证令牌以及与LLM交互。
1.配置客户端环境变量
导航到 client 目录并创建 .env.development 模板中的文件:```bash
cd client
cp .env.template .env.development
编辑 `.env.development` 根据您的配置:```bash
# 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.安装客户端依赖项```bash
npm install
### 3.确保先决条件
在运行客户端之前:
- ✅ **MCP服务器正在运行** (见上文:服务器>运行服务器)
- ✅ **Ollama 正在运行** 使用所需型号:```bash
ollama serve
ollama pull qwen3:4b
4.运行客户端
启动交互式CLI应用程序:```bash
npm start
### 5.身份验证和交互
1. 应用程序将提示您使用Entra ID进行身份验证(交互式浏览器登录)
1. 成功验证后,您将看到已注册的MCP工具
1. 在交互式提示中开始提问
**交互示例:**```text
🧠 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:
- 在中取消对OpenAI示例的注释
client/src/main.ts - 设置您的OpenAI API密钥:
export OPENAI_API_KEY=your-key - 替换
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编译为JavaScriptnpm run type-check:检查TypeScript类型而不发出文件
安全考虑
- 永不承诺
.env文件:这些文件包含敏感凭据 - 令牌验证:服务器使用Entra ID中的JWKS验证令牌
- 范围检查:确保
mcp:tools范围配置正确 - 生产部署:使用适当的密钥管理(Azure密钥库、环境变量等)
了解更多
- 模型上下文协议文档
- Vercel AI SDK
- Microsoft Entra:在Node中调用web API。JavaScript
- Ollama文件
