Argus MCP Agent

Argus Agent - SRE 助手

用于TOTVS Protheus日志分析的AI代理，采用模块化架构构建，使用了LangGraph、FastAPI、Angular以及MCP（模型上下文协议）。

🏗️ 建筑

该项目由三个主要部分组成：

1. API（api/)

• 框架使用LangGraph进行FastAPI编排
• Porta（在意大利语中意为“门”）8000
• 职责:

- 使用 PostgreSQL 的 JWT 认证 - 日志分析工作流（初步分析、深入分析、聊天分析） - 与大型语言模型（LLM）提供商（OpenAI、Google、Anthropic）的集成

• 文件记录： api/README.md（文件名，可译为“API/README.md”或保持原样，因为文件名通常不翻译，但这里为了说明其含义，可以理解为“API的README文件”）

2. MCP服务器（mcp-server/)

• 框架FastMCP（基于FastAPI）
• Porta（意大利语，意为“门”）8002
• 职责：

- 用于日志搜索的MCP工具（Elasticsearch） - 使用ChromaDB的RAG进行历史背景分析 - 时间序列中的异常检测

• 文件化/文档: mcp-server/README.md（文件名，可译为“mcp服务器/README.md”或保持原样，因为文件名通常不翻译）

3. UI（用户界面）ui/)

• 框架Angular 18 独立版 + NGINX
• Porta（意大利语）8080（开发），80（生产）
• 职责：

- 用于浏览日志的网页界面 - 带有AI的聊天机器人 - TOTVS设计系统

• 文件化/文档: ui/README.md（文件名，可翻译为“用户界面/README.md”，但通常文件名保持原样，不进行翻译）

基础设施

• PostgreSQL（译文：波斯特格瑞斯，但通常直接使用原名）用于身份验证的数据库（端口5433）
• ChromaDB（可译为“色彩数据库”或根据具体上下文译为更贴切的名称，但“色彩数据库”是较为直接的翻译）RAG向量库（端口8001）
• Elasticsearch（中文可译为“Elastic搜索引擎”或根据具体语境简化为“Elastic”）日志数据源（外部）

图表（概览）

flowchart LR
  subgraph UI
    A[Frontend Angular Browser]
  end

  subgraph API
    APIRoutes[FastAPI API 8000 - Auth Metrics Users]
  end

  subgraph MCP
    Tools[MCP Server MCP 8002 - FastMCP Tools: search_logs RAG anomalies]
  end

  subgraph Data
    ES[(Elasticsearch)]
    CH[(ChromaDB)]
    PG[(PostgreSQL)]
  end

  A -->|HTTP| APIRoutes
  A -->|HTTP| Tools
  APIRoutes |JWT| A
  Tools |JWT or Service Token| A

  Tools -->|Query| ES
  Tools -->|RAG| CH
  APIRoutes -->|Users/Auth| PG

🚀 快速设置

1. 先决条件

• Docker 和 Docker Compose （推荐）
• 或者Python 3.11+，Node.js 20+，PostgreSQL 16，ChromaDB
• 可选kubectl，Helm 3，Tilt（用于Kubernetes）

2. 环境配置

# Clone o repositório
git clone 
cd argus-mcp-agent

# Copie o arquivo de configuração
cp .env.example .env

# Edite o .env com suas credenciais
# - Chaves de API (OPENAI_API_KEY, GOOGLE_API_KEY, ANTHROPIC_API_KEY)
# - Credenciais do Elasticsearch (ES_HOST, ES_USER, ES_PASSWORD)
# - Configurações de banco de dados (se necessário)

请查阅 docs/ENV-VARIABLES.md 翻译为中文是：文档/环境变量.md 以获取环境变量的完整详情。

3. 使用Make进行执行（推荐）

该项目包括一个 Makefile 完整配置以促进发展：

# Ver todos os comandos disponíveis
make help

# Setup inicial (cria .env e venv)
make setup

# Desenvolvimento com Docker Compose
make dev

# Build e push de imagens para GCP
make docker-release

🔧 如何运行

选项1：Docker Compose（推荐）

执行整个项目的最简单方法：

# Subir todos os serviços (postgres, chromadb, api, mcp-server, ui)
docker-compose up

# Ou com rebuild
docker-compose up --build

# Parar os serviços
docker-compose down

访问应用程序：

• 用户界面（UI）地址：http://localhost:8080
• API: http://localhost:8000
• MCP 服务器：http://localhost:8002

选项2：Docker Compose 开发（带调试功能）

# Com suporte a debugging e hot-reload
docker-compose -f docker-compose.dev.yml up

选项3：本地开发（无容器）

针对每个组件的单独开发：

API

cd api
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

MCP 服务器

cd mcp-server
pip install -r requirements.txt
uvicorn tools.server:app --host 0.0.0.0 --port 8002 --reload

用户界面（UI）

cd ui
npm install
npm start  # ou ng serve
# Acesse http://localhost:4200

选项4：Tilt（Kubernetes开发）

在本地 Kubernetes 环境中进行开发：

tilt up
# Acesse a Tilt UI em http://localhost:10350

📦 部署到生产环境

使用 Helm 的 Kubernetes

# Development
helm install argus-dev ./helm/argus-agent \
  --namespace argus-dev \
  --create-namespace \
  --values k8s/dev/values.yaml

# Production
helm install argus-prod ./helm/argus-agent \
  --namespace argus-production \
  --create-namespace \
  --values k8s/prod/values.yaml

构建和推送镜像

# Login no GCP Artifact Registry
make docker-login

# Build e push com tags latest + timestamp
make docker-release

# Ou manualmente
make docker-build
make docker-push

请咨询 完整的部署文档 以了解更多详情。

图表（Kubernetes/Helm）

flowchart TB
  subgraph Namespace[argus]
    subgraph Deployments
      API[Deployment: argus-api
Pods x N]
      MCP[Deployment: argus-mcp-server
Pods x N]
      UI[Deployment: argus-ui
Pod x 1]
      CHD[Deployment: chromadb]
      PGD[Deployment: postgres]
    end

    SVC_API[Service: api 8000]
    SVC_MCP[Service: mcp 8002]
    SVC_UI[Service: ui 80]
    Ingress[Ingress NGINX]
  end

  UI --> SVC_UI --> Ingress
  API --> SVC_API --> Ingress
  MCP --> SVC_MCP --> Ingress
  MCP --> CHD
  MCP --> ES[(Elastic externo)]
  API --> PGD

📚 项目结构

argus-mcp-agent/
├── api/                      # FastAPI + LangGraph (porta 8000)
│   ├── app/                  # Código da aplicação
│   │   ├── agent/           # Workflows LangGraph
│   │   ├── api/             # Rotas da API
│   │   └── auth/            # Lógica de autenticação
│   ├── config/              # Arquivos de configuração
│   ├── prompts/             # Templates de prompts
│   ├── Dockerfile           # Imagem de produção
│   └── requirements.txt     # Dependências Python
│
├── mcp-server/              # FastMCP Server (porta 8002)
│   ├── tools/               # Implementação das ferramentas MCP
│   │   ├── server.py       # Servidor principal
│   │   ├── auth.py         # Autenticação
│   │   └── rag_manager.py  # ChromaDB RAG
│   ├── Dockerfile
│   └── requirements.txt
│
├── ui/                      # Angular 18 + NGINX (porta 8080)
│   ├── src/
│   │   ├── app/
│   │   │   ├── core/       # Auth, guards, interceptors
│   │   │   ├── features/   # Log Explorer, Login
│   │   │   └── shared/     # Componentes reutilizáveis
│   │   └── styles/         # TOTVS Design System
│   ├── nginx.conf
│   ├── Dockerfile
│   └── package.json
│
├── helm/                    # Helm charts para Kubernetes
│   └── argus-agent/
│
├── k8s/                     # Manifestos Kubernetes
│   ├── base/               # Configuração base
│   ├── dev/                # Ambiente de desenvolvimento
│   ├── staging/            # Ambiente de staging
│   └── prod/               # Ambiente de produção
│
├── docs/                    # Documentação completa
├── scripts/                 # Scripts de automação
├── docker-compose.yml       # Ambiente de desenvolvimento local
├── docker-compose.dev.yml   # Desenvolvimento com debugging
├── Makefile                # Comandos de build/deploy
└── Tiltfile                # Configuração Tilt para K8s dev

📖 文档

Geral（注：这是一个葡萄牙语词汇，直接翻译可能无对应中文含义，若作为特定名称或术语使用，需根据上下文确定具体翻译，此处提供音译）

• 📚 书籍或学习的象征 完整文件
• 🚀 表情符号“🚀”通常表示火箭、太空旅行或快速前进，可以翻译为“🚀（火箭/太空旅行/快速前进）”。不过，在实际应用中，这个表情符号往往直接以图形形式呈现，不直接翻译为文字。 快速入门指南
• 🔐（锁形符号，常用于表示保密、安全或密码等） 环境变量

部署与基础设施

• 🐳 水獭（或波浪中的海豚） 集装箱化指南
• 船 部署指南
• 🏗️ 翻译为中文是“建筑工地”或“正在建造中”。这个表情符号通常用来表示建筑、施工或建造的场景。 本地构建（GCP）
• ☸️（这个符号在中文中没有直接对应的翻译，它通常代表某种特定的文化或宗教含义，如佛教中的法轮等，具体含义需结合上下文理解。） Kubernetes（通常简称为K8s）
• 🎯 目标（靶心） 部署沙盒

组件

• 🔌（电源插头） API 文档
• 🛠️（工具箱或修理工具的符号，无直接对应中文翻译，可描述为“工具箱”或“修理工具”等意象） MCP 服务器文档
• 🎨（彩笔或涂鸦的符号，常用于表示绘画、艺术创作等） 用户界面文档
• 🌐（地球/网络） 外部访问MCP（管理控制面板/主控处理器等，具体含义根据上下文确定）

测试与验证

• ✅ 测试结果
• 🔒（锁形符号，常用于表示安全、保密或锁定状态） 身份验证测试

🛠️ 有用的Make命令

该项目包括一个 Makefile 配备各种实用命令的完整版：

发展

make help              # Mostra todos os comandos disponíveis
make setup             # Setup inicial (cria .env e venv)
make dev               # Sobe ambiente de desenvolvimento
make dev-build         # Build e sobe com docker-compose
make dev-down          # Para o ambiente
make dev-logs          # Ver logs do desenvolvimento

Docker 构建与推送

make docker-login      # Login no GCP Artifact Registry
make docker-build      # Build das 3 imagens (api, mcp-server, ui)
make docker-push       # Push para GCP registry
make docker-release    # Login + build + push (latest + timestamp)

Kubernetes & Helm

make helm-lint         # Lint do Helm chart
make helm-template     # Gera manifestos K8s
make helm-install-dev  # Instala no namespace dev
make helm-upgrade-dev  # Atualiza deployment dev
make k8s-dev-deploy    # Deploy direto com kubectl

倾斜

make tilt-up           # Inicia Tilt
make tilt-down         # Para Tilt

测试与代码检查（或代码规范检查）

make test              # Executa testes
make test-cov          # Testes com cobertura
make lint              # Linting
make clean             # Limpa artifacts de build

🌐 MCP服务器的远程使用

MCP服务器可以通过带有JWT认证的HTTP进行远程访问。

终端沙盒: https://argus.sandbox.tcloud-devops.cloudtotvs.com.br/mcp/

可用工具：

• search_logs - 在Elasticsearch中搜索日志
• retrieve_historical_context - 通过RAG（检索增强生成）的历史背景
• save_analysis_summary - 在RAG中持续进行分析
• detect_timeseries_anomalies - 异常检测

如需详细了解，请参阅：

• MCP服务器 README
• 外部访问MCP

快速示例

# 1. Login e obtenção do token
TOKEN=$(curl -s -X POST https://argus.sandbox.tcloud-devops.cloudtotvs.com.br/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":""}' | jq -r .access_token)

# 2. Buscar logs
curl -X POST https://argus.sandbox.tcloud-devops.cloudtotvs.com.br/mcp/tools/search_logs \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"index":"logs_prod_app","window":"1h"}'