Atlas MCP

阿特拉斯MCP

    

用于软件工程项目的结构化上下文和RAG的生产级MCP服务器。

O阿特拉斯MCP实施 模型上下文协议（MCP） 提供 结构化内存 LLM代理 — 技术堆栈， 约定， 架构决策和语义搜索通过RAG （检索增强生成） 与PostgreSQL + pgvector.

______________________________________________________________________

项目状态

640+个睾丸 · 93% 覆盖率 · 4工具 · 7资源

______________________________________________________________________

快速开始

选项 1：Docker（推荐）

# 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）

# 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: 无数据库（ 降级模式）

# O servidor funciona sem PostgreSQL — resources ok, RAG indisponível
uv run python -m atlas_mcp

在降级模式下，资源如 context://core/stack 它们正常工作。依赖RAG的工具（search_context）返回信息错误。

______________________________________________________________________

资源

资源是只读数据，可以通过URI访问：

______________________________________________________________________

工具

工具是代理可以执行的操作：

工具参数

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 │   │
│  └───────────────────────┘   │
└──────────────────────────────┘

背景垃圾

管道RAG

1. 分块 — MarkdownChunker 按语义标题划分文档
2. 嵌入 — EmbeddingProvider （OpenAI 或 Sentence Transformers） 生成向量
3. 存储 — VectorStore 持续没有PGVector COM搜索Cosine相似性
4. 索引 — IndexingService orquestra块→ 嵌入→ store
5. 治理 --Documentos APPROVED 自动索引； DEPRECATED 已删除

______________________________________________________________________

配置

查看 配置指南 完整的细节。

主要环境变量

______________________________________________________________________

USO com克劳德桌面

添加到您的 claude_desktop_config.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

______________________________________________________________________

测试

# 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

______________________________________________________________________

文档

______________________________________________________________________

许可证

这个项目是根据许可证 MIT许可证.