Content
<div align="center">
# 🐾 OpsCat
**The Zero-Config, Single-Binary Software Catalog & MCP Platform Engine**
*Auto-discover microservices, visualize software architecture graphs, enforce compliance scorecards, and expose your catalog natively to AI coding agents.*
[](https://go.dev)
[](LICENSE)
[](https://modelcontextprotocol.io)
<br/>
</div>
---
## 🌟 Why OpsCat?
Legacy developer portals (like Backstage) are notoriously heavy, requiring weeks of boilerplate TypeScript setup, complex yarn monorepos, and high memory footprints (>1GB RAM).
**OpsCat** reimagines platform engineering for 2026:
- ⚡ **Single Binary (< 30MB RAM)**: Written in Go with embedded React/Vite Web UI. Zero external runtime dependencies.
- 🔍 **Zero-Config Auto-Discovery**: Crawls your codebase to automatically infer tech stacks (Go, Node, Python, Rust, Java), containers (`Dockerfile`), infrastructure (`K8s`, `Helm`, `Terraform`), and APIs (`OpenAPI`, `GraphQL`, `Proto`).
- 🕸️ **Interactive 2D Dependency Graph**: Visualizes software relationships, systems, and resource dependencies in real time.
- 🤖 **Native MCP (Model Context Protocol) Server**: Gives AI coding agents (Claude, Cursor, Antigravity, Devin) direct context to query service architecture, owners, and health metrics.
- 🛡️ **Automated Compliance Scorecards**: Automatically calculates service health scores (0-100%) based on documentation, ownership, containerization, and API specs.
---
## 🚀 Quickstart
### 1. Installation
Build directly from source:
```bash
git clone https://github.com/opscat/opscat.git
cd opscat
go build -o bin/opscat ./cmd/opscat
```
### 2. Scan a Workspace Directory
Scan your current workspace to auto-discover services and save to SQLite:
```bash
./bin/opscat scan .
```
### 3. Launch the Web Portal & MCP Server
Run a single command to serve the **Glassmorphic Web UI**, **REST API**, and **MCP Server**:
```bash
./bin/opscat serve --http :8080
```
Open **[http://localhost:8080](http://localhost:8080)** in your browser!
---
## 💻 CLI Commands
OpsCat provides an intuitive command-line interface:
| Command | Description |
| :--- | :--- |
| `opscat scan [path]` | Auto-discover microservices and catalog entities in target directory |
| `opscat serve [--http :8080]` | Start combined Web UI, REST API, and MCP Server |
| `opscat serve --stdio` | Run MCP Server over stdio (for IDEs / Cursor / Claude Desktop) |
| `opscat query [name]` | Lookup catalog entities by ID, owner, or search term |
| `opscat export [-o json\|yaml\|table]` | Export catalog graph in JSON, YAML, or ASCII table format |
---
## 🤖 AI Agent Integration (MCP)
OpsCat implements the **Model Context Protocol (MCP)** specification, allowing AI agents to understand your platform topology.
### Configure with Cursor / Claude Desktop
Add to your MCP server configuration (`mcpServers` section):
```json
{
"mcpServers": {
"opscat": {
"command": "/usr/local/bin/opscat",
"args": ["serve", "--stdio"]
}
}
}
```
### Available MCP Tools for AI Agents
- `catalog_list_services`: List microservices with filtering by owner, tech stack, or minimum score.
- `catalog_get_service`: Retrieve detailed metadata, scorecards, and infrastructure specs.
- `catalog_scan_workspace`: Dynamically trigger workspace discovery.
- `catalog_get_dependencies`: Query upstream and downstream service dependencies.
---
## 📄 Manifest Spec (`catalog.yaml`)
OpsCat works out of the box with **zero configuration**. Optionally add a `catalog.yaml` to any repository root to override or enrich metadata:
```yaml
kind: service
name: payment-service
title: Global Payment Gateway Service
description: Core PCI-compliant payment processing engine.
owner: team-fintech
system: checkout-pipeline
domain: e-commerce
tags:
- payments
- fintech
- pci-dss
links:
- title: GitHub Repository
url: https://github.com/org/payment-service
type: github
- title: Grafana Dashboard
url: https://grafana.internal/d/payments
type: dashboard
relations:
- type: dependsOn
target: auth-service
- type: consumesApi
target: stripe-gateway
```
---
## 🏗️ Architecture Overview
```text
┌────────────────────────────────────────────────────────────────────────┐
│ OpsCat Single Binary │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Auto-Discovery │ │ Embedded Web UI (Vite + React) │ │
│ │ - Go, Node, Py, Rust │ │ - Glassmorphic Dashboard │ │
│ │ - Docker, K8s, Helm │ │ - Interactive 2D Vis.js Graph │ │
│ │ - Terraform, OpenAPI │ │ - Scorecard & Entity Drawer │ │
│ └────────────┬────────────┘ └──────────────────┬──────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Unified Catalog Store │ │
│ │ (Thread-Safe In-Memory Graph + SQLite Engine) │ │
│ └────────────────────────────────┬─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────┐ │
│ │ Native MCP (JSON-RPC) Server │ │
│ │ (Stdio & HTTP SSE Transports) │ │
│ └───────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘
```
---
## 🧪 Testing
Run unit tests across all core packages:
```bash
go test ./... -v
```
---
## 📜 License
Distributed under the Apache 2.0 License. See `LICENSE` for more information.
