vibe编码MCP服务器
一个最小的MCP（模型上下文协议）服务器原型，用于验证架构、测试策略、授权概念和开发工具支持。
概述
此原型公开了一个工具： getCurrentUserProfile，其基于内部授权上下文返回当前已认证用户的配置文件。
建筑
原型分为三层：
- 核心/域层 (
src/core/)：纯业务逻辑（用户数据、查找、身份验证助手、映射） - MCP工具层 (
src/tools/)：MCP工具实现 - 传输/运行时层 (
src/)：STDIO传输和服务器入口点
先决条件
- Node.js 18+（支持ES模块）
- npm或纱线
安装
npm install配置
服务器支持从以下位置加载环境变量 .env 文件。您可以复制 .env.example 到 .env 并配置您的设置：
cp .env.example .env
# Edit .env with your configuration这 npm start 和 npm run inspector 命令自动从以下位置加载变量 .env 使用 dotenv-cli.
发展
构建
npm run build这将TypeScript编译为JavaScript dist/ 目录。
测试
运行所有测试（单元+集成）：
npm test在监视模式下运行测试：
npm run test:watch运行服务器
服务器使用STDIO传输，支持两种授权模式。 如果身份验证配置无效，服务器将无法启动。
有效配置：
- 开发模式:
DEV_STATIC_AUTHORIZATION=true与DEV_STATIC_AUTHORIZATION_USER_ID必须设置 - 生产模式:
DEV_STATIC_AUTHORIZATION为假/未设置ANDJWT_JWKS_URL与JWT_EXPECTED_AUDIENCE必须设置
开发模式（静态授权）
启用开发和测试的开发模式：
选项1：使用.env文件（推荐）
创建一个 .env 项目根目录中的文件：
DEV_STATIC_AUTHORIZATION=true
DEV_STATIC_AUTHORIZATION_USER_ID=user_1然后运行：
npm start
# or
npm run inspector选项2：直接使用环境变量
# Enable dev mode and set user ID
DEV_STATIC_AUTHORIZATION=true DEV_STATIC_AUTHORIZATION_USER_ID=user_1 npm start或者在建造之后：
DEV_STATIC_AUTHORIZATION=true DEV_STATIC_AUTHORIZATION_USER_ID=user_1 node dist/index.js生产模式（JWT授权）
当 DEV_STATIC_AUTHORIZATION 未设置或设置为 false，服务器使用基于JWT的授权。JWT令牌必须由调用者作为工具参数传递：
选项1：使用.env文件（推荐）
创建一个 .env 项目根目录中的文件：
DEV_STATIC_AUTHORIZATION=false
JWT_JWKS_URL=https://your-auth-provider.com/.well-known/jwks.json
JWT_EXPECTED_AUDIENCE=your-audience
JWT_USER_ID_FIELD=sub然后运行：
npm start
# or
npm run inspector选项2：直接使用环境变量
# Production mode - configure JWT settings
JWT_JWKS_URL=https://your-auth-provider.com/.well-known/jwks.json \
JWT_EXPECTED_AUDIENCE=your-audience \
npm start在生产中调用工具：
{
"name": "getCurrentUserProfile",
"arguments": {
"token": "your-jwt-token-here"
}
}环境变量：
开发模式：
DEV_STATIC_AUTHORIZATION：设置为true或1启用开发模式DEV_STATIC_AUTHORIZATION_USER_ID：在开发模式下使用的用户ID（例如。，user_1,user_2)
生产模式（JWT配置）：
JWT_JWKS_URL：用于令牌签名验证的JWKS端点URL（必需）JWT_EXPECTED_AUDIENCE：预期受众（aud）索赔值（必填）JWT_USER_ID_FIELD：JWT负载中包含用户ID的字段名（默认值：sub)
注： JWT令牌本身由调用者作为 token 工具参数中的参数，而不是通过环境变量。
MCP检验员测试
- 构建服务器：
npm run build- 安装MCP检查器 （如果尚未安装）：
npm install -g @modelcontextprotocol/inspector- 配置MCP检查器 要使用此服务器，请执行以下操作：
启动一个mcp检查器实例，该实例将运行其自己的mcp服务器实例。 STDIO将用于通信。
- 服务器命令： npx @modelcontextprotocol/inspector node dist/index.js - 在连接到mcp服务器之前，请为开发模式设置环境变量： - DEV_STATIC_AUTHORIZATION=true - DEV_STATIC_AUTHORIZATION_USER_ID=user_1 （或 user_2)
- 检查和测试：
- 连接到mcp服务器 - 列出可用工具（应显示 getCurrentUserProfile) - 呼叫 getCurrentUserProfile 输入为空 - 验证返回的配置文件是否与当前用户匹配
可用用户（虚假数据）
user_1：Alice示例（管理员）-alice@example.comuser_2：Bob示例（用户）-bob@example.com
测试场景
有效用户（开发模式）
DEV_STATIC_AUTHORIZATION=true DEV_STATIC_AUTHORIZATION_USER_ID=user_1 npm start
# Call getCurrentUserProfile → returns Alice's profile找不到用户（开发模式）
DEV_STATIC_AUTHORIZATION=true DEV_STATIC_AUTHORIZATION_USER_ID=unknown npm start
# Call getCurrentUserProfile → returns "User not found" error无身份验证用户（生产模式-无令牌）
# Don't set DEV_STATIC_AUTHORIZATION (or set to false)
# Don't set JWT_TOKEN
npm start
# Call getCurrentUserProfile → returns "No authenticated user" error有效用户（生产模式-JWT）
# Set JWT configuration
JWT_JWKS_URL=https://auth.example.com/.well-known/jwks.json \
JWT_EXPECTED_AUDIENCE=my-app \
JWT_USER_ID_FIELD=sub \
npm start
# Call getCurrentUserProfile with token argument:
# { "name": "getCurrentUserProfile", "arguments": { "token": "valid-jwt-token" } }
# → returns user profile from JWT tokenJWT令牌无效（生产模式）
# Set JWT configuration
JWT_JWKS_URL=https://auth.example.com/.well-known/jwks.json \
JWT_EXPECTED_AUDIENCE=my-app \
npm start
# Call getCurrentUserProfile with invalid token:
# { "name": "getCurrentUserProfile", "arguments": { "token": "invalid-token" } }
# → returns "No authenticated user" error未提供令牌（生产模式）
# Set JWT configuration
JWT_JWKS_URL=https://auth.example.com/.well-known/jwks.json \
JWT_EXPECTED_AUDIENCE=my-app \
npm start
# Call getCurrentUserProfile without token argument:
# { "name": "getCurrentUserProfile", "arguments": {} }
# → returns "No authenticated user" error无身份验证用户（开发模式，无用户ID）
DEV_STATIC_AUTHORIZATION=true npm start
# DEV_STATIC_AUTHORIZATION_USER_ID not set
# Call getCurrentUserProfile → returns "No authenticated user" error项目结构
src/
├── core/ # Core/domain layer (pure logic)
│ ├── types.ts
│ ├── data.ts # Fake user data
│ ├── user-lookup.ts
│ ├── user-lookup.test.ts # Unit tests
│ ├── auth.ts
│ ├── auth.test.ts # Unit tests
│ ├── profile-mapper.ts
│ └── profile-mapper.test.ts # Unit tests
├── tools/ # MCP tool layer
│ ├── getCurrentUserProfile.ts
│ └── getCurrentUserProfile.test.ts # Unit tests
├── runtime/ # Runtime context
│ └── context.ts
└── index.ts # Entry point (stdio transport)
tests/
└── integration/ # Integration tests
└── getCurrentUserProfile.integration.test.ts测试结构
- 单元测试 (
src/**/*.test.ts)：单独测试单个功能
- 核心层： auth.test.ts, user-lookup.test.ts, profile-mapper.test.ts - 工具层： getCurrentUserProfile.test.ts （测试工具逻辑和决策流程）
- 集成测试 (
tests/integration/*.integration.test.ts)：测试多个组件协同工作
- getCurrentUserProfile.integration.test.ts （测试认证+查找+映射集成）
成功标准
✅ 核心/域层中的每个功能都可以独立进行单元测试\ ✅ 这 getCurrentUserProfile 该工具具有可靠的集成测试，涵盖成功和错误路径\ ✅ 授权概念(currentUserId → 配置文件）明确表达并经过测试\ ✅ 运行中的服务器可以通过MCP检查器进行检查和练习\ ✅ 架构可以在以后扩展（Firebase、WebSocket、更多工具），而无需重新设计