AI导哈

文档分析服务器

Sigma MCP Server是一个部署在AWS Lambda上的文档分析服务器，通过API Gateway提供接口，支持文档缓存和分析功能。

  • by ja2z
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 ja2z/mcp-server

使用说明

Sigma MCP服务器部署指南

概述

本指南指导您通过API网关将Sigma MCP服务器部署到AWS Lambda。

测试MCP服务器的示例问题

“Sigma MCP服务器的状态如何？” “检查Sigma MCP服务器连接” “测试Sigma MCP服务器连接” “Sigma MCP服务器是否正常工作？” “获取Sigma MCP服务器的当前状态” “验证Sigma MCP服务器是否正常运行”

建筑

Claude/MCP Client → API Gateway → Lambda → DynamoDB (cache)
                                    ↓
                              Secrets Manager (credentials)
                                    ↓
                               Sigma API

先决条件

  1. AWS-CLI 配置了适当的权限
  2. 地形 已安装（v1.0+）
  3. Node.js 18+和npm
  4. 西格玛API证书 （客户端ID和密码）

步骤1：准备Lambda包

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Create deployment package
npm run package

这创造了 sigma-mcp-server.zip 使用编译后的代码和依赖关系。

步骤2：配置地形变量

创建一个 terraform.tfvars 文件：

aws_region = "us-east-1"
environment = "dev"
sigma_base_url = "https://api.sigmacomputing.com"

步骤3：部署基础设施

# Initialize Terraform
terraform init

# Plan the deployment
terraform plan

# Apply the changes
terraform apply

重要：部署后，使用您的实际Sigma凭据更新Secrets Manager密钥：

aws secretsmanager update-secret \
  --secret-id "sigma-api-credentials-dev" \
  --secret-string '{"clientId":"YOUR_ACTUAL_CLIENT_ID","clientSecret":"YOUR_ACTUAL_SECRET"}'

步骤4：初始缓存填充

在MCP服务器可以搜索文档之前，需要填充文档缓存。您可以通过以下方式做到这一点：

选项A：一次性脚本

创建一个简单的脚本来填充缓存：

// populate-cache.ts
import { SigmaApiClient } from './src/sigma-client.js';
import { DocumentCache } from './src/document-cache.js';

async function populateCache() {
  const client = new SigmaApiClient({
    baseUrl: process.env.SIGMA_BASE_URL!,
    clientId: process.env.SIGMA_CLIENT_ID!,
    clientSecret: process.env.SIGMA_CLIENT_SECRET!,
  });
  
  const cache = new DocumentCache(process.env.CACHE_TABLE_NAME!);
  
  await client.initialize();
  await cache.initialize();
  await cache.refreshCache(client);
  
  console.log('Cache populated successfully');
}

populateCache().catch(console.error);

选项B：Lambda函数调用

您可以直接调用Lambda来触发缓存刷新（您需要为此添加一个端点）。

步骤5：配置Claude桌面

将您的MCP服务器添加到Claude Desktop的配置中：

{
  "mcpServers": {
    "sigma-analytics": {
      "command": "node",
      "args": [
        "path/to/mcp-client-script.js"
      ],
      "env": {
        "API_GATEWAY_URL": "https://your-api-id.execute-api.region.amazonaws.com/dev"
      }
    }
  }
}

您需要创建一个与API网关端点（而不是stdio）通信的客户端脚本。

API网关设置详细信息

Terraform创建：

  1. REST API -API网关主要资源
  2. 代理资源 - {proxy+} 捕捉所有路径
  3. 任何方法 -接受所有HTTP方法
  4. Lambda集成 -将请求路由到Lambda函数
  5. 部署 -使用调用URL创建阶段（dev/prod）

API网关流：

  1. 客户端在正文中发送带有MCP请求的HTTP POST
  2. API网关通过AWS_PROXY集成转发到Lambda
  3. Lambda处理MCP请求并返回响应
  4. API网关向客户端返回响应

环境变量

Lambda函数使用这些环境变量（由Terraform设置）：

  • SIGMA_BASE_URL -西格玛API终点
  • CACHE_TABLE_NAME -DynamoDB表名
  • NODE_ENV -环境（开发/生产）

凭据会自动从AWS Secrets Manager加载。

监控和日志

  • CloudWatch日志: /aws/lambda/sigma-mcp-server-{environment}
  • API网关日志：可以在API网关控制台中启用
  • DynamoDB指标：在CloudWatch中可用

输出

部署后，Terraform提供：

# Get the API Gateway URL
terraform output api_gateway_url

# Get other resource names
terraform output lambda_function_name
terraform output dynamodb_table_name
terraform output secrets_manager_secret_name

局部测试

在部署到AWS之前，您可以在本地测试MCP服务器：

1.设置环境变量

创建一个 .env 项目根目录中的文件（此文件已在.gitignore中）：

# Sigma API Configuration
SIGMA_CLIENT_ID=your_actual_sigma_client_id
SIGMA_CLIENT_SECRET=your_actual_sigma_client_secret
SIGMA_BASE_URL=https://api.sigmacomputing.com

# Cache Configuration
# Set to 'true' to skip caching entirely (for local testing)
# Set to 'false' or omit to use DynamoDB cache (for production)
SKIP_CACHE=true

# AWS Configuration (for local testing, these can be empty or use localstack)
AWS_REGION=us-east-1
CACHE_TABLE_NAME=sigma-documents-cache

# Environment
NODE_ENV=development

2.安装依赖项

npm install

3.测试心跳

运行本地测试脚本以验证连接：

npm run test:local

这将：

  • 检查您的环境变量
  • 构建TypeScript代码
  • 启动MCP服务器
  • 发送心跳请求
  • 显示服务器状态的响应

4.手动测试

您还可以手动运行服务器并与之交互：

# Build the project
npm run build

# Start the server
npm start

服务器将在stdio上运行并等待MCP请求。

备注：使用时 SKIP_CACHE=true，服务器将为每个请求直接从Sigma API获取数据，这对于测试很有用，但可能比使用缓存数据慢。

测试

测试部署：

调试

MCP服务器包括全面的调试功能，以帮助解决REST API调用Sigma的问题。

启用调试模式

要启用调试模式，请设置 DEBUG_MODE 环境变量：

export DEBUG_MODE=true

或者将其添加到您的 .env 文件：

DEBUG_MODE=true

调试输出

启用调试模式后，您将看到以下内容的详细日志记录：

  • MCP服务器操作：工具调用、资源请求、错误处理
  • Sigma API调用：HTTP请求、响应、身份验证
  • 文档分析：缓存操作、数据获取、解析
  • 许可证管理：令牌刷新、过期、身份验证状态

使用调试模式进行测试

使用测试脚本运行analyze_documents工具并进行调试：

# Build the project first
npm run build

# Run the test with debugging
node test-analyze-documents.js

调试日志格式

调试消息遵循以下格式：

  • 🔍 [DEBUG] -信息和进展
  • ✅ [DEBUG] -成功消息
  • ❌ [DEBUG] -错误消息
  • ⚠️ [DEBUG] -警告

常见调试场景

  1. 身份验证问题：检查令牌刷新日志
  2. API调用失败：查找HTTP状态代码和错误响应
  3. 数据解析问题：检查JSONL解析日志
  4. 缓存问题：验证缓存命中/未命中模式

故障排除步骤

  1. 检查环境变量：确保设置了所有必需的变量
  2. 验证Sigma API证书：首先使用心跳工具进行测试
  3. 检查网络连接：检查Sigma API端点是否可达
  4. 检查缓存状态：验证文档缓存是否正常工作

安全考虑

  1. API网关 在此原型中没有身份验证-请考虑为生产添加API密钥或IAM身份验证
  2. 秘密经理 通过自动轮换功能安全地存储凭据
  3. IAM角色 遵循最小特权原则
  4. 垂直路径计算机 -考虑在VPC中部署Lambda以增强网络安全性

扩展和性能

  • 拉姆达：自动称重，冷启动~1-2秒
  • DynamoDB：按需计费自动计费
  • API网关：默认情况下每秒最多可处理10000个请求
  • 缓存策略：Lambda中的内存缓存用于快速查找，DynamoDB用于持久化

故障排除

常见问题：

  1. “未找到密码” -使用真实凭据更新Secrets Manager
  2. “找不到表” -确保DynamoDB表存在并且Lambda具有权限
  3. 冷启动 -空闲时间后的第一个请求需要更长的时间
  4. CORS错误 -API网关包括CORS头

有关详细的错误信息，请查看CloudWatch日志。

相关 MCP