阿特拉斯MCP
用于软件工程项目的结构化上下文和RAG的生产级MCP服务器。
O阿特拉斯MCP实施 模型上下文协议(MCP) 提供 结构化内存 LLM代理 — 技术堆栈, 约定, 架构决策和语义搜索通过RAG (检索增强生成) 与PostgreSQL + pgvector.
项目状态
| 阶段 | 描述 | 状态 |
|---|---|---|
| 阶段 0 | 仓库基础 | ✅ 结束 |
第一阶段 MCP基础与协议✅ 结束 |
第二阶段 Context Layers 和 Persistence✅ 结束 |
第3阶段:矢量化、RAG和高级工具✅ 结束 |
第四阶段 Bootstrap、布线和服务器功能✅ 结束 |
第5阶段:文档、硬化和发布✅ 结束 |
> 640+个睾丸 · 93% 覆盖率 · 4工具 · 7资源
快速开始
选项 1:Docker(推荐)```bash
Clonar o repositório
git clone https://github.com/jhow-043/Atlas-MCP.git
cd Atlas-MCP
Copiar variáveis de ambiente e configurar
cp .env.example .env
Editar .env com sua OPENAI_API_KEY (ou usar sentence-transformers local)
Subir tudo (PostgreSQL + Atlas MCP)
docker compose up -d
Verificar saúde dos serviços
docker compose ps
### 选项 2: 本地( stdio)```bash
# Clonar e instalar
git clone https://github.com/jhow-043/Atlas-MCP.git
cd Atlas-MCP
uv sync --all-extras
# Copiar e configurar variáveis de ambiente
cp .env.example .env
# Iniciar PostgreSQL (necessário para RAG)
docker compose up -d postgres
# Iniciar o servidor
uv run python -m atlas_mcp
选项 3: 无数据库( 降级模式)```bash
O servidor funciona sem PostgreSQL — resources ok, RAG indisponível
uv run python -m atlas_mcp
> 在降级模式下,资源如 `context://core/stack` 它们正常工作。依赖RAG的工具(`search_context`)返回信息错误。
______________________________________________________________________
## 资源
资源是只读数据,可以通过URI访问:
URI · 描述
`context://core/stack` 技术堆栈(实际数据) `pyproject.toml`)
| `context://core/conventions` 代码规范(style,naming,testing)
`context://core/structure` · 项目目录结构
`context://decisions/adrs` · 注册ADR列表
| `context://decisions/adrs/{id}` 特定ADR的详细信息
`context://governance/audit-log` · 总督审计署
| `context://workflow/current` 主动开发工作流程
______________________________________________________________________
## 工具
工具是代理可以执行的操作:
名称 · 描述 · 需要 DB?
`search_context` 在项目上下文中通过 RAG 搜索语义✅
`plan_feature` · 具有上下文的结构化功能规划 · 可选
`analyze_bug` · 有上下文的结构化bug分析 · 可选
`register_adr` 创建和记录架构决策记录✅
### 工具参数
**`search_context`**```
query (str, obrigatório) — Texto de busca semântica
filters (dict, opcional) — Filtros por tipo de documento
limit (int, opcional) — Máximo de resultados (padrão: 5)
similarity_threshold (float, opcional) — Limiar de similaridade 0–1 (padrão: 0.7)
plan_feature```
title (str, obrigatório) — Nome da feature
description (str, obrigatório) — Descrição detalhada
requirements (list[str], opcional) — Requisitos
constraints (list[str], opcional) — Restrições
**`analyze_bug`**```
title (str, obrigatório) — Título do bug
description (str, obrigatório) — Descrição do problema
expected_behavior (str, opcional) — Comportamento esperado
steps_to_reproduce (list[str], opcional) — Passos para reproduzir
register_adr```
title (str, obrigatório) — Título da decisão
context (str, obrigatório) — Contexto da decisão
decision (str, obrigatório) — A decisão tomada
consequences (str, obrigatório) — Consequências
alternatives_considered (list[str], opcional) — Alternativas
tags (list[str], opcional) — Tags de categorização
______________________________________________________________________
## 建筑```
┌──────────────────────────────┐
│ MCP Client (Claude, etc) │
└────────────┬─────────────────┘
│ JSON-RPC 2.0 (stdio/SSE)
▼
┌──────────────────────────────┐
│ Atlas MCP Server │
│ ┌────────┬────────┬───────┐ │
│ │Resources│ Tools │Prompts│ │
│ └───┬────┴───┬────┴───┬───┘ │
│ ▼ ▼ ▼ │
│ ┌───────────────────────┐ │
│ │ Context Layers │ │
│ │ Core · Workflow · │ │
│ │ Decision │ │
│ └───────────┬───────────┘ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ Vectorization (RAG) │ │
│ │ Chunker → Embeddings │ │
│ │ → VectorStore │ │
│ └───────────┬───────────┘ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ Governance & │ │
│ │ Persistence │ │
│ │ PostgreSQL + pgvector │ │
│ └───────────────────────┘ │
└──────────────────────────────┘
背景垃圾
| 层次 | 描述 | 可用性 |
|---|---|---|
| 核心 | 堆栈,约定,项目结构 | 随时可用 |
| 工作流程 | 正在进行的功能、错误或重构的上下文 | 由工作流程启用 |
| 决定 | 批准的 ADR 和架构决策 | 随时可用 |
管道RAG
- 分块 —
MarkdownChunker按语义标题划分文档 - 嵌入 —
EmbeddingProvider(OpenAI 或 Sentence Transformers) 生成向量 - 存储 —
VectorStore持续没有PGVector COM搜索Cosine相似性 - 索引 —
IndexingServiceorquestra块→ 嵌入→ store - 治理 --Documentos
APPROVED自动索引;DEPRECATED已删除
配置
查看 配置指南 完整的细节。
主要环境变量
变量 · 描述 · Default
POSTGRES_HOST · 主机做PostgreSQL · localhost
POSTGRES_PORT PostgreSQL 的端口 5432
POSTGRES_USER · 用户 · atlas
POSTGRES_PASSWORD 密码 · atlas_dev
POSTGRES_DB 银行名称。 atlas_mcp
EMBEDDING_PROVIDER · openai 或 sentence-transformers · openai
OPENAI_API_KEY · API密钥do OpenAI
ATLAS_TRANSPORT · stdio 或 sse · stdio
ATLAS_LOG_LEVEL 日志级别 · INFO
ATLAS_LOG_FORMAT · text 或 json · text
USO com克劳德桌面
添加到您的 claude_desktop_config.json:```json
{
"mcpServers": {
"atlas-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "atlas_mcp"],
"cwd": "/caminho/para/Atlas-MCP",
"env": {
"POSTGRES_HOST": "localhost",
"EMBEDDING_PROVIDER": "openai",
"OPENAI_API_KEY": "sk-..."
}
}
}
}
> 对于没有API密钥的本地模式,请使用 `"EMBEDDING_PROVIDER": "sentence-transformers"`看看 使用指南 更多的例子。
______________________________________________________________________
## 项目结构```
Atlas-MCP/
├── src/atlas_mcp/ # Código-fonte principal
│ ├── __main__.py # Entry point (python -m atlas_mcp)
│ ├── server.py # Factory do servidor MCP
│ ├── bootstrap.py # Wiring de startup e shutdown
│ ├── config/ # Settings centralizado + logging
│ │ ├── settings.py # Settings (env vars + .env)
│ │ └── logging.py # Logging estruturado (text/json)
│ ├── protocol/ # Camada de protocolo MCP
│ │ ├── handler.py # ProtocolHandler (lifecycle + transports)
│ │ └── errors.py # Exceções JSON-RPC 2.0
│ ├── resources/ # 7 MCP Resources (URI-based)
│ ├── tools/ # 4 MCP Tools
│ │ ├── executor.py # ToolExecutor
│ │ ├── search_context.py # RAG search
│ │ ├── plan_feature.py # Feature planning
│ │ ├── analyze_bug.py # Bug analysis
│ │ └── register_adr.py # ADR registration
│ ├── context/ # Core, Decision, Workflow
│ ├── governance/ # GovernanceService + AuditLogger
│ ├── persistence/ # DatabaseManager + MigrationRunner
│ └── vectorization/ # Chunker, Embeddings, VectorStore, Indexing
├── tests/ # 640+ testes (93% cobertura)
│ ├── unit/ # Testes unitários
│ └── integration/ # Testes de integração (requer Docker)
├── docs/ # Documentação
│ ├── architecture/ # Contexto e arquitetura
│ ├── phases/ # Planejamento por fases
│ ├── adr/ # Architecture Decision Records
│ ├── configuration.md # Guia de configuração
│ ├── usage.md # Guia de uso
│ └── deployment.md # Guia de deployment
├── docker-compose.yml # PostgreSQL 16 + pgvector + Atlas MCP
├── Dockerfile # Multi-stage build
└── pyproject.toml # Configuração do projeto
测试```bash
Testes unitários
uv run pytest tests/unit/
Testes de integração (requer Docker com PostgreSQL)
docker compose up -d postgres
uv run pytest tests/integration/
Todos os testes com cobertura
uv run pytest --cov=src/atlas_mcp --cov-report=term-missing
Validação completa (lint + format + types + testes)
uv run ruff check .
uv run ruff format --check .
uv run mypy src/
uv run pytest
```
文档
| 配置 环境变量和操作模式
使用 · Claude Desktop,MCP检查员,前雇员
部署 · Docker编写产品,故障排除
| 贡献 如何贡献,发展流程
| 建筑 项目的背景和设计。
不良反应 · 架构决策记录
| 分支 分支政策。
许可证
这个项目是根据许可证 MIT许可证.
