Tideways MCP服务器
模型上下文协议（MCP）服务器，使AI助手能够查询 潮汐通道 性能监控数据，并为PHP应用程序提供会话性能见解。
关于Tideways: 潮汐通道 是一个专为PHP应用程序设计的强大的应用程序性能监控（APM）平台。有关技术详细信息，请参阅 REST API文档.
特性
- 会话性能洞察：获取针对AI助手优化的自然语言格式的性能数据
- AI助手集成：适用于Claude Desktop、Cursor、Claude Code和其他MCP兼容工具
- 实时性能指标：使用可配置的速率限制查询当前性能数据
- 痕量：列出和过滤跟踪，包括层分解、瓶颈检测和响应时间分析
- 问题分析：检索和分析错误、异常和性能问题
- 稳健的错误处理：通过用户友好的消息进行全面的错误处理
仓库: 5hahiL/tidway mcp服务器 许可证：MIT
先决条件
AI集成设置
这是一个专门为AI助手设计的MCP（模型上下文协议）服务器。它不能用作独立的CLI工具。
服务器使用npm包通过MCP配置与AI助手集成 tideways-mcp.
环境变量
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
TIDEWAYS_TOKEN | ✅ | - | 潮汐API访问令牌（请参阅安全部分） |
TIDEWAYS_ORG | ✅ | - | 潮汐通道组织名称 |
TIDEWAYS_PROJECT | ✅ | - | 潮汐通道项目名称 |
TIDEWAYS_BASE_URL | ❌ | https://app.tideways.io/apps/api | 潮汐道API基础URL |
TIDEWAYS_RATE_LIMIT | ❌ | 2500 | 每小时API请求-与您的计划匹配（团队/专业：2500，标准：1000，基本：250） |
TIDEWAYS_MAX_RETRIES | ❌ | 3 | 最大API重试次数 |
TIDEWAYS_REQUEST_TIMEOUT | ❌ | 30000 | API请求超时（ms） |
LOG_LEVEL | ❌ | info | 日志级别（调试、信息、警告、错误） |
AI助手集成
此服务器仅适用于MCP兼容的AI助手。它使用stdio传输。
克劳德桌面
添加到您的Claude Desktop MCP配置文件中：
地点：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json - Linux：
~/.config/claude/claude_desktop_config.json
配置（推荐-使用npx）：
{
"mcpServers": {
"tideways": {
"command": "npx",
"args": ["tideways-mcp"],
"env": {
"TIDEWAYS_TOKEN": "your_token",
"TIDEWAYS_ORG": "your_org",
"TIDEWAYS_PROJECT": "your_project"
}
}
}
}替代方案（如果全局安装）：
{
"mcpServers": {
"tideways": {
"command": "tideways-mcp",
"env": {
"TIDEWAYS_TOKEN": "your_token",
"TIDEWAYS_ORG": "your_org",
"TIDEWAYS_PROJECT": "your_project"
}
}
}
}光标IDE
Cursor通过其设置支持MCP。在Cursor的MCP设置中添加服务器配置：
- 打开光标设置
- 工具和集成
- 使用以下命令添加新服务器：
{
"mcpServers": {
"tideways": {
"command": "tideways-mcp",
"env": {
"TIDEWAYS_TOKEN": "your_token",
"TIDEWAYS_ORG": "your_org",
"TIDEWAYS_PROJECT": "your_project"
}
}
}
}带有MCP扩展的VS代码
如果使用带有MCP兼容扩展的VS Code：
{
"mcp.servers": {
"tideways": {
"command": "npx",
"args": ["tideways-mcp"],
"env": {
"TIDEWAYS_TOKEN": "your_token",
"TIDEWAYS_ORG": "your_org",
"TIDEWAYS_PROJECT": "your_project"
}
}
}
}使用AI助手
配置后，您可以向AI助手提出以下问题：
基本性能查询
- “我的应用程序的当前性能如何？”
- “显示过去24小时内的最新错误”
- “与昨天相比，我的API表现如何？”
- “目前最慢的交易是什么？”
高级跟踪分析和优化
- “分析
/api/users/{id}端点并识别瓶颈” - “查找结账过程中性能缓慢的根本原因”
- “检测我的产品列表端点中的N+1个查询并提出修复建议”
- “分析痕迹
/dashboard并推荐代码优化” - “识别用户身份验证流程中的数据库查询瓶颈”
- “在我的API终结点中查找内存泄漏或低效的代码路径”
- “分析我的应用程序中的依赖注入开销”
- “检测冗余数据库调用并建议缓存策略”
性能优化建议
- “建议对我最慢的端点进行性能改进”
- “分析我的SQL查询并建议索引策略”
- “识别查询批处理或延迟加载的机会”
- “在我的跟踪中查找低效循环或递归调用”
- “根据性能瓶颈建议代码重构”
- “分析内存使用模式并建议优化”
可用的MCP工具
所有工具都从Tideways API返回原始JSON。人工智能助手（Claude、Cursor等）对这些数据进行实际分析和解释。
get_performance_metrics
检索聚合性能指标和系统范围的统计数据。
参数：
ts（可选）：Y-m-d H:i格式的结束时间戳（例如，“2025-08-12 18:30”）m（可选）：从时间戳向后的分钟数（例如，60表示1小时，1440表示24小时）env（可选）：按特定环境筛选s（可选）：按特定服务名称筛选
会话示例：
"What's the current performance of my application?"
"Show me performance metrics for the last 6 hours"
"Get metrics for the API service in production"
"How is my web service performing in the staging environment?"
"Compare today's metrics with the last 24 hours"退货： 来自Tideways的原始性能数据，包括响应时间、吞吐量、错误率和事务故障。
get_performance_summary
以15分钟为间隔检索时间序列性能摘要数据，以进行趋势分析。
参数：
s（可选）：要过滤的服务名称（例如，“web”、“api”、“worker”）。默认值：“web”
会话示例：
"Show me performance trends over the last few hours"
"Get the performance summary for my API service"
"How has my web service been performing recently?"
"Display trends for the worker service"
"Show me response time patterns for today"退货： 以15分钟为间隔的原始时间序列数据，显示响应时间、请求计数和错误率。
get_issues
检索和分析最近的错误、异常和性能问题。
参数：
issue_type（可选）：“错误”、“slowsql”、“已弃用”、“全部”（默认值：“全部”）status（可选）：“open”、“new”、“resolved”、“not_error”、“igned”、“all”（默认值为“open”）page（可选）：分页页码（默认值：1）
会话示例：
"What errors are currently happening in my application?"
"Show me all open errors from the last 24 hours"
"Get slow SQL queries that need attention"
"Are there any new performance issues I should know about?"
"List all deprecated function calls in my code"
"Show me resolved errors to understand what was fixed"退货： Tideways的原始问题数据，包括错误类型、发生次数、受影响的端点和堆栈跟踪（如果可用）。
get_traces
分析单个跟踪样本，以进行详细的瓶颈识别和性能调试。
参数：
env（可选）：环境名称（例如，“生产”、“暂存”）s（可选）：服务名称（例如，“web”、“api”、“worker”）transaction_name（可选）：按特定事务/端点名称筛选has_callgraph（可选）：仅返回包含详细调用图数据的跟踪search（可选）：基于事务名称、主机和URL的单词搜索min_date（可选）：YYYY-MM-DD HH:MM格式的最小日期（需要max_date）max_date（可选）：YYYY-MM-DD HH:MM格式的最大日期（需要min_date）min_response_time_ms（可选）：最小响应时间过滤器max_response_time_ms（可选）：最大响应时间过滤器sort_by（可选）：“response_time”、“date”、“memory”（默认值：“responsetime”）sort_order（可选）：“ASC”、“DESC”（默认值：“DESC）
会话示例：
"Analyze traces for the /api/products endpoint and find bottlenecks"
"Show me the slowest requests from the last hour with details"
"Find traces with callgraph data for the checkout process"
"What's causing slow response times in my user registration flow?"
"Detect N+1 query problems in my product listing page"
"Analyze memory usage patterns in my API endpoints"
"Find database bottlenecks in the /dashboard endpoint"
"Show me traces where response time is over 2 seconds"退货： Tideways的原始跟踪数据，包括每次请求的时间、层分解（SQL、Redis、HTTP等）、瓶颈标志和调用图数据 has_callgraph: true 已设置。使用 has_callgraph: true 了解最深入的调试细节。
get_historical_data
以可配置的粒度检索特定日期的历史性能数据。
参数：
date（必填）：YYYY-MM-DD格式的日期granularity（可选）：“天”、“周”、“月”（默认值：“日”）
会话示例：
"Get historical performance data for August 1st, 2025"
"Show me weekly performance trends for last Monday"
"Compare this month's performance with last month"
"How did my application perform on 2025-07-15?"
"Get daily performance data for the past week"
"Show me monthly trends for the last quarter"退货： 来自Tideways的指定日期和粒度的原始历史性能数据。
发展
项目结构
├── src/
│ ├── config/ # Configuration management
│ ├── lib/ # Core libraries
│ │ ├── errors.ts # Error handling utilities
│ │ ├── logger.ts # Structured logging
│ │ └── tideways-client.ts # Tideways API client
│ ├── tools/ # MCP tool implementations
│ │ ├── definitions.ts # Tool schema definitions
│ │ ├── registry.ts # Tool execution registry
│ │ └── handlers/ # Individual tool handlers
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions
│ ├── server.ts # Main MCP server implementation
│ └── index.ts # Application entry point
├── tests/ # Test suites
└── dist/ # Compiled JavaScript (generated)运行测试
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in watch mode
npm run test:watch
# Run type checking
npm run typecheck建筑
# Build TypeScript to JavaScript
npm run build
# Clean build artifacts
npm run clean代码质量
# Run linter
npm run lint
# Fix linting issues
npm run lint:fix
# Format code
npm run format建筑
核心组件
- MCP服务器 (
src/server.ts)：实现MCP协议的主服务器，处理工具定义和路由 - 潮汐道API客户 (
src/lib/tideways-client.ts)：具有速率限制、重试逻辑和安全措施的HTTP客户端 - 工具注册表 (
src/tools/)：模块化工具系统，每个MCP工具都有单独的处理器 - 错误处理器 (
src/lib/errors.ts)：通过用户友好的消息进行集中错误处理 - 日志记录器 (
src/lib/logger.ts)：用于监控和调试的结构化JSON日志记录 - 配置 (
src/config/index.ts)：基于环境的配置管理
数据流
AI Assistant ←→ MCP Protocol (stdio) ←→ TidewaysMCPServer → TidewaysClient → Tideways API
↓
Raw JSON Response → AI Assistant响应格式原理
此服务器使用 原始JSON方法 为了获得最佳性能：
- API到-LLM的直接管道：工具归还
JSON.stringify(apiData, null, 2)无格式 - 零处理开销：没有复杂的格式化、缓存或解释逻辑
- 完整的数据保存：LLM接收所有可用数据以进行灵活分析
- 最小维护：无需维护或调试格式化程序或缓存逻辑
利率限制策略
- 可配置速率限制器：设置
TIDEWAYS_RATE_LIMIT以匹配您的Tideways计划（默认值：2500/hr） - 直接API调用：所有请求都直接进入Tideways API，无需缓存层
- 重试逻辑：指数回退的瞬态故障自动重试
🛡️ 安全
- API令牌安全存储在环境变量中
- 授权标头在日志中自动编辑为
Bearer [REDACTED] - 遵守潮汐API限制的费率限制
- 所有MCP功能参数的输入验证
- 错误消息中没有记录或暴露敏感数据
- 自动安全扫描：CodeQL、Snyk、TruffleLog、GitLeaks
📊 监控
服务器提供结构化的JSON日志用于监控：
{
"timestamp": "2025-08-09T10:00:00.000Z",
"level": "info",
"message": "Tool called",
"context": {
"toolName": "get_performance_metrics",
"arguments": {"time_range": "24h"}
}
}🔧 故障排除
常见问题
认证错误
Error: Authentication failed. Please check your API token.- 验证
TIDEWAYS_TOKEN正确且具有所需的范围(metrics,issues,traces) - 支票令牌尚未过期
- 确保组织和项目名称正确
超出费率限制
Error: Rate limit exceeded. Please try again later.- 集
TIDEWAYS_RATE_LIMIT以匹配您的实际计划限额 - 等待速率限制重置（显示在错误消息中）
- 内置的速率限制符合您配置的限制
连接问题
Error: Network error: Unable to connect to Tideways API.- 检查网络连接
- 验证潮汐API是否可以从您的网络访问
- 检查公司防火墙是否阻止API访问
app.tideways.io - 卷曲测试：
curl -H "Authorization: Bearer YOUR_TOKEN" https://app.tideways.io/apps/api/_token
MCP集成问题
Error: MCP server not responding or connection failed- 重新启动您的AI助手（Claude Desktop、Cursor等）
- 验证MCP配置文件语法是否正确
- 检查服务器命令路径是否正确
- 确保在MCP配置中正确设置环境变量
- 请先尝试手动运行服务器：
npx tideways-mcp
调试模式
启用调试日志记录以进行详细的故障排除：
# When running directly
LOG_LEVEL=debug npx tideways-mcp
# In MCP configuration, add to env:
{
"env": {
"LOG_LEVEL": "debug",
"TIDEWAYS_TOKEN": "your_token",
...
}
}获取帮助
- 检查日志：调试模式提供有关请求和响应的详细信息
- 验证配置：仔细检查所有环境变量和MCP设置
- 测试API访问：使用curl验证您的Tideways API证书是否有效
- 报告问题: 包含调试日志和配置详细信息
贡献
欢迎投稿！
- 创建要素分支：
git checkout -b your-feature - 进行更改并添加测试：
npm test - 提交拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。