atlas-introspect-mcp

ATLAS가 스스로를 보고 편집할 수 있게 해주는 MCP 서버입니다:

HTTP API를 사용하는 이유

채팅 기록, 워크스페이스, 프롬프트는 모두 하나의 DuckDB 파일(data/chat_history.db)에 저장됩니다. DuckDB는 단일 작성자(single-writer)이며 ATLAS 프로세스가 전체 수명 동안 쓰기 잠금을 보유하므로, 두 번째 프로세스가 파일을 열면 읽기 전용이라도 잠금 충돌로 실패합니다. 따라서 이 서버는 대신 루프백 HTTP를 통해 ATLAS에 요청합니다. 이는 또한 사용자별 범위 지정이 여기서 재구현되는 대신 ATLAS에 의해 강제된다는 것을 의미합니다.

mcp.json과 prompts/*.md만 직접 다룹니다. ATLAS에는 이 둘에 대한 API가 없습니다.

별도의 프로세스라는 점이 ATLAS로 다시 호출하는 것을 안전하게 만듭니다. ATLAS는 이 서버의 stdio 응답을 기다리는 동안 자체 이벤트 루프는 요청을 처리할 수 있는 상태로 유지됩니다. 동일한 작업을 수행하는 프로세스 내 도구는 교착 상태(deadlock)에 빠질 것입니다.

Related MCP server: Atlas MCP Server

Identity

모든 쿼리는 X-User-Email로 전송되는 한 사용자로 범위가 지정됩니다. DEBUG_MODE=true일 때 ATLAS는 해당 헤더를 존중합니다. 꺼져 있으면 헤더는 인증 프록시가 제공했을 값이므로 동일한 플래그가 어느 쪽이든 작동합니다. 기본값은 test@test.com입니다. 이는 디버그 모드에서 ATLAS가 대체하는 테스트 사용자이며, 따라서 이 호스트에서 UI를 통해 생성된 대화의 소유자입니다.

Install

git clone https://github.com/garland3/atlas-introspect-mcp
cd atlas-introspect-mcp
uv venv .venv
uv pip install -e ".[dev]" --python .venv/bin/python

독립 실행형 확인(ATLAS 실행 중):

.venv/bin/atlas-introspect-mcp --list-tools
.venv/bin/python -c "
import asyncio; from fastmcp import Client
from fastmcp.client.transports import StdioTransport
async def m():
    async with Client(StdioTransport(command='.venv/bin/atlas-introspect-mcp', args=['--stdio'])) as c:
        print(await c.call_tool('atlas_status', {}))
asyncio.run(m())"

Register with ATLAS

ATLAS config/mcp.json에 추가하세요(절대 경로 — 명령은 셸의 PATH가 아닌 서비스 관리자의 PATH에서 찾습니다). 그런 다음 ATLAS를 다시 시작하세요:

"atlas_introspect": {
  "command": [
    "/abs/path/to/atlas-introspect-mcp/.venv/bin/atlas-introspect-mcp",
    "--stdio",
    "--atlas-url", "http://127.0.0.1:8090",
    "--user", "test@test.com"
  ],
  "cwd": "/abs/path/to/atlas-introspect-mcp",
  "transport": "stdio",
  "groups": ["users"],
  "description": "Introspect and configure this ATLAS instance: browse chat history, read/edit config/mcp.json, manage workspaces and custom prompts.",
  "short_description": "ATLAS self-introspection",
  "compliance_level": "Public"
}

명령에 "--read-only"를 추가하면 보기 전용 빌드가 됩니다. 그러면 모든 변경 도구는 쓰는 대신 거부합니다.

포트: stdio는 필요 없습니다. --transport http는 기본적으로 8101입니다. 포트 8080은 완전히 거부합니다. k3s를 실행하는 호스트에서 klipper-lb는 8080을 Traefik으로 DNAT합니다(127.0.0.1에서도 포함). 따라서 거기에 바인딩된 서버는 아무것도 수신하지 못하며 모든 요청은 로그에 아무 줄도 없이 빈 500으로 돌아옵니다.

Configuration

모든 플래그에는 환경 변수에 해당하는 것이 있습니다.

Tools

대화 (읽기 전용) — list_conversations, search_conversations, get_conversation, list_conversation_tags

config/mcp.json — get_mcp_config, upsert_mcp_server, delete_mcp_server, replace_mcp_config

워크스페이스 — list_workspaces, create_workspace, update_workspace, delete_workspace

사용자 정의 프롬프트 — list_custom_prompts, get_custom_prompt, create_custom_prompt, update_custom_prompt, delete_custom_prompt

디스크의 프롬프트 파일 — list_prompt_files, read_prompt_file, write_prompt_file

상태 — atlas_status

Things that will bite

• mcp.json 편집은 즉시 적용되지 않습니다. ATLAS는 시작 시 stdio 서버를 생성합니다. 모든 쓰기 도구는 결과에 그렇게 명시합니다. systemctl --user restart atlas 또는 ./redeploy.sh --no-pull로 적용하세요.

• 자신의 항목을 편집하는 것은 작동하지만 재시작 시에만 적용됩니다. 그 시점에 잘못된 항목이 있으면 이 서버가 사라지고 ATLAS 내부에서 수정할 수 없습니다. 백업은 파일 옆에 mcp.json.bak-<stamp>로 저장됩니다.

• upsert_mcp_server는 항목을 통째로 교체합니다. 병합하지 않습니다. 먼저 읽고, 변경하고, 전체를 다시 보내세요. 워크스페이스 config와 프롬프트의 content도 마찬가지입니다.

• 대화 도구는 설계상 읽기 전용입니다. ATLAS에는 삭제 엔드포인트가 있지만 여기서는 의도적으로 노출하지 않습니다.

• write_prompt_file은 인스턴스의 모든 채팅을 변경합니다. 먼저 백업하고 mcp.json과 마찬가지로 다음 재시작 시 적용됩니다.

Tests

.venv/bin/pytest

이 테스트는 임시 디렉터리를 대상으로 파일 편집 및 검증 로직(원자적 쓰기, 백업, 순회 거부, lint 경고, 읽기 전용 모드)을 다룹니다. 실행 중인 ATLAS가 필요 없습니다.