Twining MCP Server

문제점

Claude Code와 함께 아키텍처 결정을 내리는 데 두 시간을 보냅니다. MongoDB 대신 PostgreSQL을 선택합니다. 인증을 위해 JWT를 결정합니다. 결제 모듈에서 경쟁 상태(race condition)를 발견합니다. 그러고 나서 세션이 종료됩니다.

내일 새로운 세션을 시작합니다. Claude는 무슨 일이 있었는지 전혀 모릅니다. 결정 사항은 사라졌습니다. 경고도 사라졌습니다. 근거도 사라졌습니다. 모든 것을 다시 설명해야 합니다. 더 나쁜 것은 Claude가 어제의 선택과 모순되는 내용을 조용히 제안하는 것입니다.

여러 에이전트를 사용하면 상황은 더 악화됩니다. 에이전트 A는 REST를 선택합니다. 에이전트 B는 같은 서비스에 대해 gRPC를 선택합니다. 서로의 존재를 모릅니다. 코드가 컴파일되지 않을 때야 비로소 알게 됩니다.

컨텍스트 윈도우는 일시적입니다. 프로젝트의 결정 사항은 그렇지 않아야 합니다.

Twining의 해결 방법

Twining은 AI 에이전트에게 지속적인 프로젝트 메모리를 제공하는 MCP 서버입니다. 결정 사항은 컨텍스트가 초기화되어도 유지됩니다. 새로운 세션은 정보를 갖춘 상태로 시작됩니다. 다중 에이전트 작업은 조율된 상태로 유지됩니다.

# Install in 10 seconds
/plugin marketplace add daveangulo/twining-mcp
/plugin install twining@twining-marketplace

수행한 작업을 자연어로 기록하세요:

twining_record({
  summary: "Added Redis caching to UserService",
  decisions: ["Chose Redis over Memcached — need persistence across restarts"],
  assumptions: ["Read-heavy workload (10:1 ratio)"],
  scope: "src/services/"
})

Twining은 귀하의 결정을 구조화된 기록으로 파싱하여 근거, 거부된 대안, 도메인을 자동으로 추출합니다. 양식 작성 없이 도구 호출 한 번으로 끝납니다.

새로운 세션을 시작하고 즉시 파악하세요:

twining_assemble({ task: "optimize the caching layer", scope: "src/services/" })

Twining은 모든 결정, 경고, 발견 사항을 작업과의 관련성에 따라 점수를 매긴 다음, 우선순위에 따라 토큰 예산을 채웁니다. 정보의 홍수나 재설명 없이 필요한 정확한 컨텍스트를 얻을 수 있습니다.

왜 그렇게 결정되었는지 물어보세요:

twining_why({ scope: "src/auth/middleware.ts" })

파일에 대한 전체 결정 체인을 반환합니다: 무엇이 결정되었는지, 언제, 왜, 어떤 대안이 거부되었는지, 그리고 어떤 커밋이 이를 구현했는지 알려줍니다.

왜 CLAUDE.md만 사용하지 않나요?

CLAUDE.md는 정적입니다. 한 번 작성하고 수동으로 업데이트해야 합니다. 결정이 발생하는 즉시 기록하지 않으며, 근거나 대안을 추적하지 않고, 에이전트 간의 충돌을 감지하지 못하며, 토큰 예산 내에서 컨텍스트를 선택적으로 구성할 수 없습니다.

Twining은 동적입니다. 모든 twining_decide 호출은 구조화된 결정을 기록합니다. 모든 twining_post는 발견 사항이나 경고를 공유합니다. 모든 twining_assemble은 관련성을 점수화하여 현재 작업에 필요한 내용을 정확하게 전달합니다. .twining/ 디렉토리는 프로젝트의 살아있는 조직적 기억입니다.

왜 오케스트레이터가 아닌가요?

오케스트레이터(에이전트 스웜 및 계층적 조정자 등)는 작업을 할당하여 업무를 라우팅합니다. Twining은 상태를 공유하여 조율합니다. 차이점은 중요합니다:

• 오케스트레이터는 조율 컨텍스트를 자신의 컨텍스트 윈도우에 보관합니다. 이는 윈도우가 채워짐에 따라 성능이 저하되는 단일 실패 지점입니다.

• Twining의 블랙보드는 조율 상태를 에이전트의 윈도우 외부에서 유지하므로, 정보 손실 없이 컨텍스트 초기화 후에도 살아남습니다.

에이전트는 블랙보드를 읽음으로써 스스로 작업을 선택합니다. 중앙 병목 현상이 없습니다. 컨텍스트를 누락시키는 릴레이도 없습니다. 모든 에이전트는 다른 모든 에이전트의 결정과 경고를 직접 확인합니다.

설치

플러그인 설치 (권장)

# Add the marketplace (one-time)
/plugin marketplace add daveangulo/twining-mcp

# Install the plugin
/plugin install twining@twining-marketplace

MCP 서버, 기술(skills), 수명 주기 후크 및 커밋 전 강제 적용 기능을 포함합니다. 두 가지 관문: 작업 전 twining_assemble, 커밋 전 twining_record — 후크가 이 두 가지를 자동으로 강제합니다.

팀 자동 설치

팀원이 복제 시 Twining을 바로 사용할 수 있도록 저장소의 .claude/settings.json에 다음을 커밋하세요:

{
  "extraKnownMarketplaces": {
    "twining-marketplace": {
      "source": {
        "source": "github",
        "repo": "daveangulo/twining-mcp"
      }
    }
  },
  "enabledPlugins": {
    "twining@twining-marketplace": true
  }
}

팀원이 저장소 폴더를 신뢰하면 Claude Code가 자동으로 마켓플레이스와 플러그인을 설치합니다.

MCP 전용 설치

비 Claude-Code 클라이언트(Cursor, Windsurf 등)의 경우:

claude mcp add twining -- npx -y twining-mcp --project .

또는 .mcp.json에 추가하세요:

{
  "mcpServers": {
    "twining": {
      "command": "npx",
      "args": ["-y", "twining-mcp", "--project", "."]
    }
  }
}

MCP 서버 지침은 초기화 응답에 자동으로 포함됩니다.

수동 설치에서 업그레이드

이전에 Twining을 수동으로 구성했다면 플러그인으로 전환하세요:

1. 수동 MCP 서버 제거: claude mcp remove twining

2. 플러그인 설치: /plugin marketplace add daveangulo/twining-mcp 후 /plugin install twining@twining-marketplace

3. 정리: .claude/settings.json에서 Twining 후크 제거, .claude/agents/twining-aware.md가 있다면 제거, CLAUDE.md에서 Twining 섹션 제거 (이제 기술이 이를 처리함)

4. 유지: .twining/ 디렉토리 (모든 상태 보존)

5. 확인: /twining:status

최대한 활용하기

플러그인은 기술(skills)을 통해 에이전트 지침을 자동으로 처리합니다. MCP 전용 설치 경로의 경우, 에이전트가 자동으로 사용하도록 프로젝트의 CLAUDE.md에 Twining 지침을 추가하세요. 복사 가능한 템플릿은 **docs/CLAUDE_TEMPLATE.md**를 참조하세요.

대시보드

http://localhost:24282에서 웹 대시보드가 자동으로 시작됩니다. 결정 사항, 블랙보드 항목, 지식 그래프 및 에이전트 상태를 탐색할 수 있습니다. TWINING_DASHBOARD_PORT를 통해 구성 가능합니다.

포함된 내용

핵심 도구 (항상 사용 가능)

에이전트가 모든 세션에서 사용하는 도구입니다:

twining_record는 "Redis 대신 Memcached 선택 — 지속성 필요"와 같은 자연어 결정을 수락하고 이를 근거, 거부된 대안, 추론된 도메인이 포함된 구조화된 기록으로 자동 파싱합니다. 또한 가정, 제약 조건, 영향을 받는 파일 및 종속성 체인도 수락하여 결정 저장소가 고충실도 컨텍스트 구성을 위해 필요한 모든 것을 제공합니다.

확장 도구 (full_surface: true 사용 시)

고급 워크플로우(심층 결정 관리, 그래프 탐색, 다중 에이전트 조율)를 위한 도구입니다:

.twining/config.yml에서 활성화:

tools:
  full_surface: true

작동 원리

모든 상태는 .twining/에 일반 파일로 존재합니다. 블랙보드는 JSONL, 결정 사항, 그래프, 에이전트 및 핸드오프는 JSON으로 저장됩니다. 모든 것은 jq로 쿼리 가능하고, grep 가능하며, git-diff 가능합니다. 데이터베이스도, 클라우드도, 계정도 없습니다.

아키텍처 계층:

• 저장소 — 동시 액세스를 위한 잠금 기능이 있는 파일 기반 저장소

• 엔진 — 결정 추적, 블랙보드, 그래프 탐색, 토큰 예산 기반 컨텍스트 구성, 에이전트 조율

• 임베딩 — @huggingface/transformers를 통한 로컬 all-MiniLM-L6-v2, 지연 로딩 및 키워드 폴백 지원. 서버는 임베딩 문제로 인해 시작에 실패하지 않습니다.

• 대시보드 — cytoscape.js 그래프 시각화 및 vis-timeline을 갖춘 읽기 전용 웹 UI

• 도구 — Zod로 검증된 MCP 도구 정의, 도구 표면과 1:1 매핑

전체 사양은 TWINING-DESIGN-SPEC.md를 참조하세요.

FAQ

Twining이 Claude Code를 느리게 하나요? 아니요. 로컬 MCP 서버이므로 도구 호출은 로컬 파일 읽기/쓰기입니다. 의미론적 검색은 처음 사용할 때 지연 로딩됩니다.

Cursor, Windsurf 또는 다른 MCP 클라이언트와 함께 사용할 수 있나요? 네. Twining은 표준 MCP 서버입니다. 모든 MCP 호스트가 연결할 수 있습니다.

데이터는 어디로 가나요? 모든 조율 상태는 .twining/에 로컬로 저장됩니다. 도구 호출 메트릭은 .twining/metrics.jsonl(gitignored)에 로컬로 저장됩니다. 선택적인 익명 텔레메트리를 활성화할 수 있습니다. 아래 분석을 참조하세요.

Twining은 에이전트 오케스트레이터인가요? 아니요. 조율 상태 계층입니다. 에이전트가 무엇을 결정했는지, 왜 결정했는지 포착하여 미래의 에이전트가 해당 지식을 사용할 수 있게 합니다. 오케스트레이터, 에이전트 팀 또는 독립형 세션과 함께 사용하세요.

분석

Twining은 제공하는 가치를 이해하는 데 도움이 되는 3계층 분석 시스템을 포함합니다.

인사이트 대시보드 탭

웹 대시보드에는 다음을 보여주는 인사이트 탭이 포함되어 있습니다:

• 가치 메트릭 — 맹목적인 결정 방지율, 경고 인지, tested_by 그래프 관계를 통한 테스트 커버리지, 커밋 추적성, 결정 수명 주기, 지식 그래프 통계 및 에이전트 조율 메트릭

• 도구 사용량 — 도구별 호출 횟수, 오류율, 평균/P95 지연 시간

• 오류 분석 — 도구 및 오류 코드별로 그룹화된 오류

모든 가치 메트릭은 기존 .twining/ 데이터에서 계산되므로 새로운 데이터 수집이 필요하지 않습니다.

도구 호출 메트릭

모든 MCP 도구 호출은 타이밍 및 성공/오류 추적 기능이 자동으로 계측됩니다. 메트릭은 .twining/metrics.jsonl(gitignored — 아키텍처 데이터가 아닌 운영 데이터)에 로컬로 저장됩니다.

로컬 메트릭 수집을 비활성화하려면 .twining/config.yml에 다음을 설정하세요:

analytics:
  metrics:
    enabled: false

옵트인 텔레메트리

익명화된 집계 사용 데이터는 Twining 개선을 위해 선택적으로 PostHog로 전송될 수 있습니다. 기본적으로 비활성화되어 있습니다. 활성화하려면 .twining/config.yml에 다음을 추가하세요:

analytics:
  telemetry:
    enabled: true

이것으로 끝입니다. PostHog 프로젝트 키는 소스 코드에 내장되어 있습니다. 자체 PostHog 인스턴스를 실행하는 경우 posthog_api_key 및 posthog_host로 재정의할 수 있습니다.

전송되는 정보: 도구 이름, 호출 지속 시간, 성공/실패 불리언, 서버 버전, OS, 아키텍처.

전송되지 않는 정보: 파일 경로, 결정 내용, 에이전트 이름, 오류 메시지, 도구 인수, 환경 변수.

개인정보 보호 안전장치:

• DO_NOT_TRACK=1 환경 변수는 항상 구성을 재정의합니다.

• CI=true는 텔레메트리를 자동으로 비활성화합니다.

• 식별자는 호스트 이름 + 프로젝트 루트의 SHA-256 해시입니다 (원시 경로가 아님).

• 네트워크 오류는 조용히 처리됩니다 (재시도 없음).

• posthog-node는 선택적 종속성입니다 (설치되지 않은 경우 정상적으로 작동하지 않음).

개발

npm install       # Install dependencies
npm run build     # Build
npm test          # Run tests (800+ tests)
npm run test:watch

Node.js >= 18이 필요합니다.

CI/CD

두 개의 GitHub Actions 워크플