内容
<div align="center">
# 🐾 OpsCat
**零配置、单二进制软件目录和MCP平台引擎**
*自动发现微服务，展示软件架构图，强制执行合规性记分卡，并原生地将目录暴露给AI编码代理。*
[](https://go.dev)
[](LICENSE)
[](https://modelcontextprotocol.io)
<br/>
</div>
---
## 🌟 为什么选择 OpsCat？
传统的开发者门户（如 Backstage）非常臃重，需要数周的样板 TypeScript 设置、复杂的 yarn monorepos 和高内存占用（>1GB RAM）。
**OpsCat** 为 2026 年重新构想了平台工程：
- ⚡ **单二进制（< 30MB RAM）**：使用 Go 编写，嵌入 React/Vite Web UI。零外部运行时依赖。
- 🔍 **零配置自动发现**：爬取代码库以自动推断技术栈（Go、Node、Python、Rust、Java）、容器（`Dockerfile`）、基础设施（`K8s`、`Helm`、`Terraform`）和 API（`OpenAPI`、`GraphQL`、`Proto`）。
- 🕸️ **交互式 2D 依赖图**：实时展示软件关系、系统和资源依赖。
- 🤖 **原生 MCP（模型上下文协议）服务器**：为 AI 编码代理（Claude、Cursor、Antigravity、Devin）提供直接上下文，以查询服务架构、所有者和健康指标。
- 🛡️ **自动合规记分卡**：根据文档、所有权、容器化和 API 规范自动计算服务健康分数（0-100%）。
---
## 🚀 快速开始
### 1. 安装
直接从源码构建：
```bash
git clone https://github.com/opscat/opscat.git
cd opscat
go build -o bin/opscat ./cmd/opscat
```
### 2. 扫描工作空间目录
扫描当前工作空间以自动发现服务并保存到 SQLite：
```bash
./bin/opscat scan .
```
### 3. 启动 Web 门户和 MCP 服务器
运行单个命令以提供 **Glassmorphic Web UI**、**REST API** 和 **MCP 服务器**：
```bash
./bin/opscat serve --http :8080
```
在浏览器中打开 **[http://localhost:8080](http://localhost:8080)**！
---
## 💻 CLI 命令
OpsCat 提供直观的命令行界面：
| 命令 | 描述 |
| :--- | :--- |
| `opscat scan [路径]` | 在目标目录中自动发现微服务和目录实体 |
| `opscat serve [--http :8080]` | 启动综合 Web UI、REST API 和 MCP 服务器 |
| `opscat serve --stdio` | 通过 stdio 运行 MCP 服务器（适用于 IDE / Cursor / Claude Desktop） |
| `opscat query [名称]` | 按 ID、所有者或搜索词查找目录实体 |
| `opscat export [-o json\|yaml\|table]` | 以 JSON、YAML 或 ASCII 表格格式导出目录图 |
---
## 🤖 AI 代理集成（MCP）
OpsCat 实现 **模型上下文协议（MCP）** 规范，允许 AI 代理了解您的平台拓扑。
### 与 Cursor / Claude Desktop 配置
添加到您的 MCP 服务器配置（`mcpServers` 部分）：
```json
{
"mcpServers": {
"opscat": {
"command": "/usr/local/bin/opscat",
"args": ["serve", "--stdio"]
}
}
}
```
### AI 代理的可用 MCP 工具
- `catalog_list_services`：列出微服务，并按所有者、技术栈或最低分数进行筛选。
- `catalog_get_service`：检索详细的元数据、记分卡和基础设施规格。
- `catalog_scan_workspace`：动态触发工作空间发现。
- `catalog_get_dependencies`：查询上游和下游服务依赖项。
---
## 📄 清单规范（`catalog.yaml`）
OpsCat 开箱即用，**零配置**。可选地在任何仓库根目录中添加 `catalog.yaml` 以覆盖或丰富元数据：
```yaml
kind: service
name: payment-service
title: 全球支付网关服务
description: 核心 PCI 合规支付处理引擎。
owner: team-fintech
system: checkout-pipeline
domain: e-commerce
tags:
- payments
- fintech
- pci-dss
links:
- title: GitHub 仓库
url: https://github.com/org/payment-service
type: github
- title: Grafana 仪表盘
url: https://grafana.internal/d/payments
type: dashboard
relations:
- type: dependsOn
target: auth-service
- type: consumesApi
target: stripe-gateway
```
---
## 🏗️ 架构概述
```text
┌────────────────────────────────────────────────────────────────────────┐
│ OpsCat 单二进制 │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────────────────┐ │
│ │ 自动发现 │ │ 嵌入式 Web UI（Vite + React） │ │
│ │ - Go, Node, Py, Rust │ │ - Glassmorphic 仪表盘 │ │
│ │ - Docker, K8s, Helm │ │ - 交互式 2D Vis.js 图 │ │
│ │ - Terraform, OpenAPI │ │ - 记分卡和实体抽屉 │ │
│ └────────────┬────────────┘ └──────────────────┬──────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 统一目录存储 │ │
│ │ （线程安全内存图 + SQLite 引擎） │ │
│ └────────────────────────────────┬─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────┐ │
│ │ 原生 MCP（JSON-RPC）服务器 │ │
│ │ （Stdio 和 HTTP SSE 传输） │ │
│ └───────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘
```
---
## 🧪 测试
运行所有核心包的单元测试：
```bash
go test ./... -v
```
---
## 📜 许可证
在 Apache 2.0 许可证下分发。有关更多信息，请参见 `LICENSE`。
