使用说明

MCP天文台

MCP服务器的新遗迹- 现在开源！

用于模型上下文协议服务器的实时可观察性、监控和成本跟踪平台，具有 会话监控 通过克劳德。

🎯 视觉

只需询问Claude即可监控您的MCP服务器：

“我的服务器健康吗？”
“哪些工具运行缓慢？”
“显示最近的错误”

Claude使用MCP Observatory工具以自然语言回答问题，并提供可操作的见解。

🏗️ 建筑

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  Your MCP Server                                                │
│  ├─ Instrumented with @lukrlier/mcp-observatory-sdk           │
│  └─ Events → FileReporter → metrics.ndjson                     │
│                                                                 │
└─────────────────┬───────────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  MCP Observatory Server                                         │
│  ├─ FileDataSource reads metrics.ndjson                        │
│  └─ Exposes 5 MCP tools for querying metrics                   │
│                                                                 │
└─────────────────┬───────────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  Claude Desktop                                                 │
│  ├─ User asks: "What are my server metrics?"                   │
│  ├─ Claude calls get_server_metrics tool                       │
│  └─ Claude responds with natural language insights             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

✨ 特性

✅ 100%开源和自托管

所有代码都是开源的（SDK+MCP服务器）
数据保持100%本地（NDJSON文件）
不需要外部依赖
团队可选云服务

📊 综合指标

工具调用统计（计数、持续时间、成功率）
性能分析（P50、P95、P99延迟）
错误跟踪和调试
成本估算
健康评分和建议

🔌 插件架构

SDK记者：文件、控制台、云
MCP数据源：文件、PostgreSQL、云
易于通过自定义实现进行扩展

🤖 会话监控

通过Claude使用自然语言查询指标：

“向我展示慢速工具”
“今天发生了什么错误？”
“这要花多少钱？”

🚀 快速入门（5分钟）

1.安装SDK

npm install @lukrlier/mcp-observatory-sdk

2.检测您的MCP服务器

import { createObservatory } from '@lukrlier/mcp-observatory-sdk';

const observatory = createObservatory({
  reporter: 'file',
  filePath: './metrics.ndjson',
});

// Track tool calls
server.onToolCall(async (toolName, params) => {
  const start = Date.now();
  try {
    const result = await executeTool(toolName, params);
    observatory.trackToolCall({
      toolName,
      parameters: params,
      duration: Date.now() - start,
      success: true,
    });
    return result;
  } catch (error) {
    observatory.trackError({
      errorType: error.name,
      message: error.message,
      stack: error.stack,
    });
    throw error;
  }
});

3.安装MCP天文台服务器

npm install -g @lukrlier/mcp-observatory-server

4.配置克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-observatory": {
      "command": "mcp-observatory-server",
      "args": ["--file", "/path/to/your/metrics.ndjson"]
    }
  }
}

5.问克劳德

重新启动Claude Desktop并询问：

“我的MCP服务器的指标是什么？”
“是否存在任何性能问题？”

📦 项目结构

mcp-observatory/
├── packages/
│   ├── sdk/                # @lukrlier/mcp-observatory-sdk
│   │   ├── src/
│   │   │   ├── reporters/  # FileReporter, ConsoleReporter, CloudReporter
│   │   │   ├── factory.ts  # createObservatory()
│   │   │   └── types.ts    # Type definitions
│   │   └── package.json
│   │
│   └── mcp-server/         # @lukrlier/mcp-observatory-server
│       ├── src/
│       │   ├── datasources/ # FileDataSource, PostgresDataSource, CloudDataSource
│       │   ├── index.ts     # MCP Server implementation
│       │   └── types.ts     # Type definitions
│       └── package.json
│
├── examples/
│   └── basic-file-reporter/  # Complete example with SDK + MCP Server

🎓 例子

基本文件报告器

完整的独立示例：示例/基本文件报告器

cd examples/basic-file-reporter
pnpm install
pnpm start    # Generate sample metrics
pnpm test     # Test MCP Server reads them correctly

看示例/基本文件报告器/README.md 详细演练。

🔧 报告程序选项

File Reporter（建议95%的用户使用）

createObservatory({
  reporter: 'file',
  filePath: './metrics.ndjson',
  batchSize: 50,
  batchTimeout: 5000,
  sampling: 1.0, // 100%
});

控制台报告程序（调试）

createObservatory({
  reporter: 'console',
  debug: true,
});

Cloud Reporter（可选托管服务）（即将推出）

createObservatory({
  reporter: 'cloud',
  apiKey: 'sk_xxx',
  endpoint: 'https://api.mcp-observatory.dev/v1/ingest',
});

🛠️ MCP服务器选项

文件数据源（独立）

mcp-observatory-server --file ./metrics.ndjson --debug

PostgreSQL数据源（生产）（即将推出）

mcp-observatory-server --postgres "postgresql://localhost:5432/mcp"

云数据源（托管）（即将推出）

mcp-observatory-server --cloud sk_xxx

📊 可用的MCP工具

MCP服务器公开了Claude可以使用的5个工具：

get_server_metrics -总体服务器运行状况和性能
- 可选的 server_id -如果省略，则返回所有服务器的聚合指标
get_tool_stats -特定工具的详细统计数据
- 可选的 server_id -如果省略，则返回所有服务器的统计信息
get_error_logs -最近调试时出现的错误
- 可选的 server_id -如果省略，将从所有服务器返回错误
get_cost_estimate -API估计成本
- 可选的 server_id -如果省略，则返回所有服务器的成本
分析性能 -基于人工智能的性能洞察
- 可选的 server_id -如果省略，则分析所有服务器

备注：所有工具都支持查询，无需 server_id 获取所有MCP服务器的汇总指标。

🧪 开发状态

✅ 完成:

具有插件架构的SDK（FileReporter、ConsoleReporter、CloudReporter）
带FileDataSource的MCP服务器
完整的端到端示例
测试通过（SDK:12/12）
文档

🚧 进行中:

PostgreSQL数据源
云数据源
其他示例
集成测试

📅 计划的:

仪表板（可选云服务）
告警
多服务器监控
团队协作

❓ 常见问题解答

这会将数据发送到外部服务器吗？

否！默认情况下，使用FileReporter时，所有数据都保持100%本地。度量值存储在您计算机上的NDJSON文件中。云报告器是可选的，默认情况下是禁用的。

性能开销是多少？

最小。SDK使用：

异步事件批处理（默认值：50个事件或5秒超时）
采样支持（可选：仅跟踪X%的呼叫）
非阻塞写入

典型开销：每次工具调用<1ms。

我可以在生产中使用这个吗？

对！基于文件的方法已为大多数用例做好生产准备。对于高容量场景（>1000请求/秒），请考虑：

使用PostgreSQL数据源（即将推出）
调整批量大小
启用采样（例如，10%的呼叫）

SDK和MCP服务器有什么区别？

软件开发工具包 (@lukrlier/mcp-observatory-sdk)：检测MCP服务器以收集指标
MCP服务器 (@lukrlier/mcp-observatory-server)：通过Claude Desktop查询指标

两者都需要：SDK收集数据→ MCP服务器允许克劳德查询它。

指标多久写入一次磁盘？

指标是分批编写的：

每50个事件（可通过以下方式配置 batchSize)
每5秒（可通过以下方式配置 batchTimeout)
关机时（优雅冲洗）

我可以创建自定义记者吗？

对！实施 Reporter 接口：

interface Reporter {
  reportToolCall(event: ToolCallEvent): Promise<void>;
  reportError(event: ErrorEvent): Promise<void>;
  shutdown(): Promise<void>;
}

看 packages/sdk/src/reporters/ 例如。

收集了哪些数据？

SDK收集：

工具名称、参数、持续时间、成功/错误状态
时间戳、服务器ID
错误类型、消息、堆栈跟踪（选择加入）
自定义元数据（可选）

除非在参数或元数据中明确包含敏感数据，否则不会收集敏感数据。

度量文件有大小限制吗？

没有硬性限制，但是：

NDJSON文件随事件线性增长
建议：每天或每周轮换文件
使用原木轮换工具（如logrotate）进行生产
考虑使用PostgreSQL DataSource进行长期存储

如何测试我的仪器？

运行基本示例：

cd examples/basic-file-reporter
pnpm install
pnpm start  # Generates sample metrics
pnpm test   # Verifies MCP Server reads them

或者使用ConsoleReporter进行调试：

createObservatory({ reporter: 'console', debug: true });

我可以监视多个MCP服务器吗？

对！每台服务器应：

写入唯一的度量文件（例如。， server1.ndjson, server2.ndjson)
有一个独特的 serverId 在SDK配置中
在中单独配置 claude_desktop_config.json

v1.0.1中的新功能：您现在可以跨所有服务器查询指标，而无需指定 server_id:

User: "What are my overall server metrics?"
Claude: Calls get_server_metrics() without server_id
        Returns aggregated metrics for all servers

这有助于：

一次获取所有MCP服务器的概览
比较不同服务器的性能
确定哪个服务器有问题

🤝 贡献

欢迎投稿！看贡献.md 作为指导方针。

📜 许可证

麻省理工学院-参见许可证了解详情。

🙏 学分

内置：

模型上下文协议通过Anthropic
黄道带用于验证
TypeScript、Node.js、pnpm

问题？ 打开一个问题