Trailmark MCP 서버

Trailmark MCP 서버는 를 감싸는 독립형 MCP 래퍼입니다.

ToB의 사용 방식을 이해하고 있지만, 제 사용 사례에서는 여러 그래프를 분석하고 서비스할 수 있는 MCP 서버가 필요합니다. 이 서버는 여러 저장소를 스캔할 수 있으며, LLM은 각각의 저장소에서 정보를 개별적으로 요청할 수 있습니다.

대부분 VS Code의 Github Copilot을 통해 OpenAI GPT-5.5로 작성되었습니다. 문서 및 개발 지원을 위해 LLM을 ai-docs 디렉토리로 안내하십시오.

요구 사항

• Python 3.12+

• uv

프로젝트 메타데이터:

• 패키지 이름: trailmark-mcp

• CLI 명령어: trailmark-mcp

설치

런타임 및 개발 의존성 설치:

uv sync --group dev

빠른 시작

stdio를 통해 서버 시작:

uv run trailmark-mcp serve --transport stdio

MCP 클라이언트 없이 직접 스캔 경로 스모크 테스트:

uv run trailmark-mcp scan /path/to/repo

필요 시 스캔 중 사전 분석 건너뛰기:

uv run trailmark-mcp scan /path/to/repo --skip-preanalysis

서버 작동 방식

기본 수명 주기 진입점은 open_repository(...)입니다.

동작 요약:

• 스냅샷이 없으면 서버가 소스를 스캔하고, 선택적으로 사전 분석을 실행한 뒤 첫 번째 스냅샷을 저장합니다.

• 스냅샷이 존재하고 rescan=False인 경우, 서버는 최신 스냅샷을 라이브 세션으로 다시 로드합니다.

• rescan=True인 경우, 서버는 소스에서 다시 빌드하고 새로운 스냅샷을 저장합니다.

따라서 일반적인 흐름은 다음과 같습니다:

1. open_repository 호출

2. 반환된 세션에 대해 그래프 도구 사용

3. 지속성이 필요한 의미 있는 메모리 내 변경 후 save_snapshot 호출

세션 모델

session_id는 Trailmark 코어 상태가 아닌 MCP 래퍼 상태입니다.

현재 의미 체계:

• 각 open_repository(...) 호출은 새로운 세션 ID를 생성합니다.

• 여러 라이브 세션이 공존할 수 있습니다.

• 도구는 특정 그래프를 대상으로 하기 위해 session_id를 허용합니다.

• session_id가 생략되면 가장 최근에 열린 활성 세션이 사용됩니다.

• 기본 세션을 닫으면 가장 최근에 열린 나머지 세션이 승격됩니다.

세션이 어떤 저장소를 가리키는지 확인하려면 current_repository(session_id=...)를 사용하십시오.

공개 MCP 도구

수명 주기:

• open_repository

• current_repository

• close_repository

• save_snapshot

탐색:

• graph_summary

• diff_graphs

• search_nodes

• callers_of

• callees_of

• ancestors_of

• reachable_from

• paths_between

• entrypoint_paths_to

• attack_surface

• complexity_hotspots

• functions_that_raise

컨텍스트 및 변경:

• subgraph

• annotations_of

• findings

• nodes_with_annotation

• run_preanalysis

• annotate_node

• clear_annotations

• augment_findings

참고:

• diff_graphs(before_session_id, after_session_id)는 after를 새로운 상태로 취급합니다.

• search_nodes는 contains, exact, suffix를 지원합니다.

• scan_repository 및 tool_manifest와 같은 도우미 표면은 의도적으로 더 이상 공개 런타임의 일부가 아닙니다.

스냅샷 동작

스냅샷은 이 서버 저장소가 아닌 분석된 저장소 아래에 기록됩니다:

<target-repo>/.trailmark/snapshots/<timestamp>/

현재 스냅샷 아티팩트 포함 항목:

• graph.json

• summary.json

• entrypoints.json

• hotspots.json

• subgraphs.json

• scan-metadata.json

스냅샷은 라이브 세션으로 다시 로드하는 것을 지원합니다. 소스에서 새로운 빌드가 명시적으로 필요할 때 rescan=True를 사용하십시오.

저장소 레이아웃

주요 파일:

• src/trailmark_mcp/cli.py: scan 및 serve를 위한 CLI 진입점

• src/trailmark_mcp/mcp_app.py: MCP 도구 등록

• src/trailmark_mcp/tool_catalog.py: 노출된 도구에 대한 선언적 메타데이터

• src/trailmark_mcp/services/registry.py: 세션 추적

• src/trailmark_mcp/services/runtime.py: Trailmark 기반의 주요 런타임 동작

개발

집중 테스트 제품군 실행:

uv run --group dev pytest tests/test_tool_catalog.py tests/test_registry.py tests/test_stdio_server.py

현재 CI는 Python 3.12에서 동일한 집중 테스트 제품군을 실행합니다.

확장 규칙:

1. 런타임 동작 추가 또는 변경

2. mcp_app.py에 도구 등록

3. tool_catalog.py의 메타데이터 업데이트

4. 테스트 업데이트

5. 공개 동작이 변경된 경우 문서 업데이트

VS Code에서 사용

VS Code는 작업 공간 수준의 mcp.json 파일을 통해 이 서버를 MCP를 통해 직접 실행할 수 있습니다.

일반적인 설정:

1. VS Code에서 이 저장소를 엽니다.

2. uv sync --group dev로 의존성이 설치되었는지 확인합니다.

3. .vscode/mcp.json에 서버 정의를 유지합니다.

4. MCP 클라이언트가 stdio를 통해 서버를 시작하도록 합니다.

이 저장소에는 이미 로컬 사용을 위한 .vscode/mcp.json이 포함되어 있습니다.

mcp.json 예시:

{
  "servers": {
    "trailmark-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "trailmark-mcp",
        "serve",
        "--transport",
        "stdio"
      ]
    }
  }
}

더 큰 다중 프로젝트 작업 공간에서 이 서버를 사용하는 경우, 해당 작업 공간 루트의 .vscode/mcp.json에 동일한 정의를 복사하고 명령어가 uv 및 이 프로젝트를 사용할 수 있는 환경에서 실행되는지 확인하십시오.