cyanheads/atlas-mcp-server

ATLAS (Adaptive Task & Logic Automation System)는 LLM 에이전트 (LLM Agents)를 위한 프로젝트, 지식 및 작업 관리 시스템입니다.

다음과 같은 3노드 (3-node) 아키텍처를 기반으로 구축되었습니다:

+-------------------------------------------+
| PROJECT |
|-------------------------------------------|
...

Model Context Protocol (MCP) 서버로 구현된 ATLAS는 LLM 에이전트가 프로젝트 관리 데이터베이스와 상호작용할 수 있도록 하여, 프로젝트, 작업 및 지식 항목을 관리할 수 있게 해줍니다.

중요 버전 참고 사항: 버전 1.5.4는 데이터베이스로 SQLite를 사용하는 마지막 버전입니다. 버전 2.0부터는 Neo4j를 사용하도록 완전히 재작성되었으며, 다음 중 하나가 필요합니다:

• Docker를 사용한 셀프 호스팅 (저장소에 docker-compose 포함)
• Neo4j AuraDB 클라우드 서비스 사용: https://neo4j.com/product/auradb/

버전 2.5.0은 이전 구조를 대체하는 새로운 3노드 시스템 (Projects, Tasks, Knowledge)을 도입합니다.

• 개요 (Overview)
• 기능 (Features)
• 설치 (Installation)
• 서버 실행 (Running the Server)
• 웹 UI (Web UI) (실험적 기능)
• 설정 (Configuration)
• 프로젝트 구조 (Project Structure)
• 도구 (Tools)
• 리소스 (Resources)
• 데이터베이스 백업 및 복구 (Database Backup and Restore)
• 예시 (Examples)
• 라이선스 (License)

ATLAS는 Model Context Protocol (MCP)을 구현하여 다음과 같은 요소들을 통해 LLM과 외부 시스템 간의 표준화된 통신을 가능하게 합니다:

클라이언트 (Clients): Claude Desktop, IDE 및 기타 MCP 호환 클라이언트
서버 (Servers): 프로젝트, 작업 및 지식 관리를 위한 도구 및 리소스
LLM 에이전트 (LLM Agents): 서버의 관리 기능을 활용하는 AI 모델

Atlas 플랫폼은 이러한 구성 요소들을 하나의 응집된 시스템으로 통합합니다:

프로젝트-태스크 관계 (Project-Task Relationship): 프로젝트는 프로젝트 목표를 달성하는 데 필요한 실행 가능한 단계인 태스크 (Tasks)를 포함합니다. 태스크는 상위 프로젝트로부터 컨텍스트 (Context)를 상속받는 동시에, 개별 작업 항목에 대한 세밀한 추적을 제공합니다.

지식 통합 (Knowledge Integration): 프로젝트와 태스크 모두 지식 항목 (Knowledge items)으로 보강될 수 있으며, 이를 통해 팀원들에게 필요한 정보와 컨텍스트를 제공합니다.

의존성 관리 (Dependency Management): 프로젝트와 태스크 모두 의존성 관계 (Dependency relationships)를 지원하여, 선행 조건 및 순차적 실행 요구 사항이 포함된 복잡한 워크플로우 (Workflows)를 구현할 수 있습니다.

통합 검색 (Unified Search): 플랫폼은 엔티티 간 교차 검색 (Cross-entity search) 기능을 제공하여, 사용자가 다양한 기준에 따라 관련 프로젝트, 태스크 또는 지식을 찾을 수 있도록 합니다.

기능 영역	주요 역량
프로젝트 관리 (Project Management)	- 포괄적 추적: 프로젝트 메타데이터, 상태 및 풍부한 콘텐츠(노트, 링크 등)를 관리하며, 일괄 작업 (Bulk operations)을 기본적으로 지원합니다. - 의존성 및 관계 처리: 프로젝트 간 의존성을 자동으로 검증하고 추적합니다.
태스크 관리 (Task Management)	- 태스크 라이프사이클 관리: 태스크의 전체 라이프사이클 (Lifecycle) 동안 생성, 추적 및 업데이트를 수행합니다. - 우선순위 지정 및 분류: 더 나은 조직화를 위해 우선순위 레벨을 할당하고 태그 (Tags)로 태스크를 분류합니다. - 의존성 추적: 구조화된 워크플로우를 생성하기 위해 태스크 의존성을 설정합니다.
지식 관리 (Knowledge Management)	- 구조화된 지식 저장소: 프로젝트 관련 정보에 대해 검색 가능한 저장소를 유지합니다. - 도메인 분류: 쉬운 검색을 위해 도메인과 태그별로 지식을 정리합니다. - 인용 지원: 지식 항목에 대한 출처와 참조를 추적합니다.
그래프 데이터베이스 통합 (Graph Database Integration)	- 네이티브 관계 관리: 강력한 데이터 무결성을 위해 Neo4j의 ACID 준수 트랜잭션 (ACID-compliant transactions)과 최적화된 쿼리 (Queries)를 활용합니다. - 고급 검색 및 확장성: 퍼지 매칭 (Fuzzy matching) 및 와일드카드 (Wildcards)를 사용한 속성 기반 검색을 수행하면서도 높은 성능을 유지합니다.

통합 검색 (Unified Search)

• 엔티티 간 검색 (Cross-Entity Search): 콘텐츠, 메타데이터 또는 관계를 기반으로 관련 프로젝트, 작업 또는 지식을 찾습니다. - 유연한 쿼리 옵션 (Flexible Query Options): 대소문자 구분 없음 (case-insensitive), 퍼지 매칭 (fuzzy), 그리고 고급 필터링 옵션을 지원합니다.

저장소 복제 (Clone the repository):
git clone https://github.com/cyanheads/atlas-mcp-server.git cd atlas-mcp-server

의존성 설치 (Install dependencies):
npm install

Neo4j 설정 (Configure Neo4j):
Neo4j 인스턴스가 실행 중이며 접근 가능한지 확인하세요. 제공된 Docker 설정을 사용하여 시작할 수 있습니다:
docker-compose up -d

.env 파일에 Neo4j 연결 세부 정보를 업데이트하세요 (설정(Configuration) 섹션 참조).

프로젝트 빌드 (Build the project):
npm run build

대부분의 MCP 클라이언트 (MCP Clients)는 서버를 자동으로 실행하지만, 테스트 또는 개발 목적으로 다음 명령어를 사용하여 수동으로 실행할 수도 있습니다.

ATLAS MCP Server는 통신을 위해 여러 전송 메커니즘 (transport mechanisms)을 지원합니다:

표준 입출력 (Standard I/O, stdio):
이것은 기본 모드이며 일반적으로 로컬 MCP 클라이언트(예: IDE 확장 프로그램)와의 직접적인 통합에 사용됩니다.
npm run start:stdio

이 방식은 MCP_TRANSPORT_TYPE=stdio 설정을 사용합니다.

스트리밍 가능한 HTTP (Streamable HTTP):
이 모드는 서버가 HTTP를 통해 MCP 요청을 수신할 수 있게 하며, 원격 클라이언트 또는 웹 기반 통합에 적합합니다.
npm run start:http

이 방식은 MCP_TRANSPORT_TYPE=http 설정을 사용합니다. 서버는 .env 파일에 정의된 호스트 및 포트(예: MCP_HTTP_HOST 및 MCP_HTTP_PORT, 기본값은 127.0.0.1:3010)에서 대기합니다. 원격으로 접속하는 경우 방화벽이 연결을 허용하는지 확인하세요.

프로젝트, 작업 및 지식의 세부 정보를 볼 수 있는 기본적인 웹 UI (Web UI)를 사용할 수 있습니다.

UI 열기 (Opening the UI):

• 브라우저에서 UI를 직접 열려면 터미널에서 다음 명령어를 실행하세요:
  npm run webui

• 브라우저에서 UI를 직접 열려면 터미널에서 다음 명령어를 실행하세요:

기능 (Functionality):

• 여기에서 Web UI의 예시 스크린샷을 볼 수 있습니다.

환경 변수 (Environment variables)는 MCP 클라이언트의 클라이언트 설정에 설정하거나, .env 파일에 설정해야 합니다.

로컬 개발을 위해 프로젝트 루트 (project root)에 있는 .env 파일에 설정해야 합니다.

# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
...

사용 가능한 모든 환경 변수 (environment variables), 설명 및 기본값은 src/config/index.ts를 참조하십시오.

MCP 클라이언트를 구성하는 방법은 클라이언트 자체와 선택한 전송 유형 (transport type)에 따라 달라집니다. 일부 클라이언트(예: mcp-inspector)는 서버 설정을 정의하기 위해 프로젝트 루트의 mcp.json 파일을 사용할 수 있으므로, 필요에 따라 업데이트하십시오.

Stdio 전송 방식 (예시 구성):

{
"mcpServers": {
"atlas-mcp-server-stdio": {
...

Streamable HTTP 방식 (예시 구성):
클라이언트가 Streamable HTTP를 통해 MCP 서버에 연결하는 것을 지원하는 경우, 클라이언트 설정에 서버의 엔드포인트 (endpoint, 예: http://localhost:3010/mcp)를 제공합니다.

{
"mcpServers": {
"atlas-mcp-server-http": {
...

참고: 서버가 클라이언트의 즉각적인 작업 디렉토리 (working directory)에 있지 않은 경우, 클라이언트 명령을 구성할 때 args에 항상 절대 경로 (absolute paths)를 사용하십시오. 클라이언트의 env 블록에 있는 MCP_AUTH_SECRET_KEY는 예시일 뿐입니다. 클라이언트와 서버 간 통신을 위한 실제 토큰 처리 방식은 클라이언트의 기능과 서버의 인증 메커니즘 (예: Authorization 헤더에 JWT 전송)에 따라 달라집니다.

코드베이스는 모듈형 구조를 따릅니다:

src/
├── config/ # 설정 관리 (index.ts)
├── index.ts # 메인 서버 진입점 (entry point)
...

ATLAS는 Model Context Protocol을 통해 호출할 수 있는 프로젝트, 작업 및 지식 관리를 위한 포괄적인 도구 모음을 제공합니다.

도구 이름 (Tool Name)	설명 (Description)	주요 인자 (Key Arguments)
atlas_project_create
새로운 프로젝트를 생성합니다 (단일/일괄).
mode ('single'/'bulk'), id (단일 모드 시 클라이언트가 생성한 선택적 ID), 프로젝트 상세 정보 (name, description, status, urls, completionRequirements, dependencies, outputFormat, taskType). 일괄 (bulk) 모드의 경우 projects (프로젝트 객체 배열)를 사용합니다. responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').
atlas_project_list
프로젝트 목록을 나열합니다 (전체/상세).
mode ('all'/'details', 기본값: 'all'), id (상세 모드용), 필터 (status, taskType), 페이지네이션 (page, limit), 포함 항목 (includeKnowledge, includeTasks), responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').
atlas_project_update
기존 프로젝트를 업데이트합니다 (단일/일괄).
mode ('single'/'bulk'), id (단일 모드용), updates 객체. 일괄 (bulk) 모드의 경우 projects (각각 id와 updates를 포함하는 객체 배열)를 사용합니다. responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').
atlas_project_delete
프로젝트를 삭제합니다 (단일/일괄).
mode ('single'/'bulk'), id (단일 모드용) 또는 projectIds (일괄 모드용 배열). responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').

도구 이름 (Tool Name)	설명 (Description)	주요 인자 (Key Arguments)
atlas_task_create	새로운 작업(task)을 생성합니다 (단일/일괄).	mode ('single'/'bulk'), id (선택 사항, 클라이언트 생성 ID), projectId, 작업 상세 정보 (title, description, priority, status, assignedTo, urls, tags, completionRequirements, dependencies, outputFormat, taskType). 일괄 모드(bulk mode)의 경우, tasks (작업 객체 배열)를 사용합니다. responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').
atlas_task_update	기존 작업을 업데이트합니다 (단일/일괄).	mode ('single'/'bulk'), id (단일 모드용), updates 객체. 일괄 모드(bulk mode)의 경우, tasks (id와 updates를 각각 포함하는 객체 배열)를 사용합니다. responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').
atlas_task_delete	작업을 삭제합니다 (단일/일괄).	mode ('single'/'bulk'), id (단일 모드용) 또는 taskIds (일괄 모드용 배열). responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').
atlas_task_list	특정 프로젝트의 작업 목록을 나열합니다.	projectId (필수), 필터 (status, assignedTo, priority, tags, taskType), 정렬 (sortBy, sortDirection), 페이지네이션 (page, limit), responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').

도구 이름 (Tool Name)	설명 (Description)	주요 인자 (Key Arguments)
atlas_knowledge_add	새로운 지식 항목을 추가합니다 (단일/일괄).	mode ('single'/'bulk'), id (선택 사항, 클라이언트 생성 ID), projectId, 지식 상세 정보 (text, tags, domain, citations). 일괄 (bulk) 모드의 경우, knowledge (지식 객체 배열)를 사용합니다. responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').
atlas_knowledge_delete	지식 항목을 삭제합니다 (단일/일괄).	mode ('single'/'bulk'), id (단일 모드용) 또는 knowledgeIds (일괄 모드용 배열). responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').
atlas_knowledge_list	특정 프로젝트의 지식 항목 목록을 나열합니다.	projectId (필수), 필터 (tags, domain, search), 페이지네이션 (page, limit), responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').

도구 이름 (Tool Name)	설명 (Description)	주요 인자 (Key Arguments)
atlas_unified_search	엔티티 (entities) 전반에 걸쳐 통합 검색을 수행합니다.	value (검색어, 필수), property (선택 사항: 지정 시 해당 속성에 대해 정규 표현식 (regex) 검색을 수행하며, 생략 시 전체 텍스트 검색 (full-text search)을 수행함), 필터 (entityTypes, taskType, assignedToUserId), 옵션 (caseInsensitive (기본값: true, 정규 표현식용), fuzzy (기본값: false, 정규 표현식 'contains' 또는 Lucene 전체 텍스트 퍼지 검색용)), 페이지네이션 (page, limit), responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').

도구 이름 (Tool Name)	설명 (Description)	주요 인자 (Key Arguments)
atlas_deep_research	Atlas 지식 베이스 (knowledge base) 내에 계층적 계획을 생성하여 구조화된 심층 조사 (deep research) 프로세스를 시작합니다.	projectId (필수), researchTopic (필수), researchGoal (필수), scopeDefinition (선택 사항), subTopics (필수 객체 배열, 각 객체는 question (필수), initialSearchQueries (선택 사항 배열), nodeId (선택 사항), priority (선택 사항), assignedTo (선택 사항), initialStatus (선택 사항, 기본값: 'todo')를 포함), researchDomain (선택 사항), initialTags (선택 사항), planNodeId (선택 사항), createTasks (선택 사항, 기본값: true), responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').

도구 이름 (Tool Name)	설명 (Description)	주요 인자 (Key Arguments)
atlas_database_clean	파괴적 작업: 데이터베이스를 완전히 초기화하여 모든 프로젝트, 작업 및 지식을 삭제합니다.	acknowledgement (확인을 위해 true로 설정해야 함, 필수), responseFormat ('formatted'/'json', 선택 사항, 기본값: 'formatted').

ATLAS는 표준 MCP 리소스 엔드포인트 (resource endpoints)를 통해 프로젝트, 작업 및 지식 데이터를 노출합니다.

리소스 이름 (Resource Name)	설명 (Description)
atlas://projects	페이지네이션 (pagination)을 지원하는 Atlas 플랫폼 내의 모든 프로젝트 목록.
atlas://tasks	페이지네이션 및 필터링 (filtering)을 지원하는 Atlas 플랫폼 내의 모든 작업 목록.
atlas://knowledge	페이지네이션 및 필터링 (filtering)을 지원하는 Atlas 플랫폼 내의 모든 지식 항목 목록.