tacit-mcp

AI 어시스턴트를 Tacit 빌딩 디지털 트윈에 연결하는 MCP 서버입니다. 건물, 장비, 센서 및 구역에 대해 자연어로 질문하세요.

Claude Desktop, Claude Code, Cursor, Windsurf 및 모든 MCP 호환 클라이언트와 함께 작동합니다.

기능

4가지 읽기 전용 도구:

GraphQL 도구에는 전체 스키마 참조가 포함되어 있어 AI 모델이 별도의 문서 없이도 쿼리를 작성할 수 있습니다.

빠른 시작

옵션 A: npx (권장 — 설치 불필요)

npx -y @tacit/mcp-server

MCP 클라이언트를 이 서버로 지정하기만 하면 됩니다(아래 구성 참조). 복제나 빌드가 필요 없습니다.

옵션 B: 복제 및 빌드

git clone https://github.com/ucl-sbde/tacit-mcp.git
cd tacit-mcp
npm install
npm run build

Tacit API 키가 필요합니다. app.betacit.com의 Site Settings > API Keys에서 키를 발급받으세요.

연결 방법

1. Stdio 전송 (로컬, 기본값)

표준 방식 — MCP 클라이언트가 서버를 자식 프로세스로 실행합니다. 개인용 컴퓨터에서 사용하기에 가장 적합합니다.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)을 편집하세요:

{
  "mcpServers": {
    "tacit": {
      "command": "npx",
      "args": ["-y", "@tacit/mcp-server"],
      "env": {
        "TACIT_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

프로젝트의 .mcp.json에 추가하세요:

{
  "mcpServers": {
    "tacit": {
      "command": "npx",
      "args": ["-y", "@tacit/mcp-server"],
      "env": {
        "TACIT_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

.cursor/mcp.json에 추가하세요:

{
  "mcpServers": {
    "tacit": {
      "command": "npx",
      "args": ["-y", "@tacit/mcp-server"],
      "env": {
        "TACIT_API_KEY": "your-api-key"
      }
    }
  }
}

2. Streamable HTTP 전송 (원격)

서버를 지속적인 HTTP 서비스로 실행합니다. 팀 단위, 클라우드 배포 및 사용자가 로컬에 Node.js를 설치할 수 없는 환경에 가장 적합합니다.

# Start the HTTP server
TACIT_API_KEY=your-api-key npm run start:http

# Or with npx
TACIT_API_KEY=your-api-key npx --package @tacit/mcp-server tacit-mcp-http

서버는 기본적으로 http://0.0.0.0:3001/mcp에서 수신 대기합니다.

모든 MCP 클라이언트에서 연결

Bearer 토큰과 함께 서버 URL을 클라이언트에 지정하세요:

{
  "mcpServers": {
    "tacit": {
      "type": "streamable-http",
      "url": "https://your-host:3001/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

HTTP 구성

상태 확인

GET /health → { "status": "ok", "transport": "streamable-http", "sessions": 3 }

3. OAuth 2.1 (엔터프라이즈)

사용자가 API 키를 관리하는 대신 Tacit 로그인 흐름을 통해 인증하도록 하려는 프로덕션 배포용:

TACIT_OAUTH_ISSUER=https://app.betacit.com npm run start:http

다음 기능을 활성화합니다:

• 동적 클라이언트 등록 — MCP 클라이언트가 자동으로 등록됨

• 인증 코드 + PKCE — 사용자가 Tacit 웹 UI를 통해 로그인

• 토큰 갱신 — 재인증 없이 세션 유지

• 토큰 취소 — 깔끔한 세션 종료

OAuth를 지원하는 MCP 클라이언트(예: Claude Desktop)는 .well-known/oauth-authorization-server 메타데이터 엔드포인트를 통해 인증 구성을 자동으로 검색합니다.

4. Docker

docker run -p 3001:3001 -e TACIT_API_KEY=your-api-key tacit/mcp-server

위의 HTTP 전송 구성을 사용하여 연결하세요.

사용 예시

연결 후 AI 어시스턴트에게 다음과 같이 질문해 보세요:

• "내 건물 사이트 목록을 보여줘"

• "Tower West에 있는 AHU는 무엇인가요?"

• "AHU-001의 온도 센서를 보여줘"

• "지난 24시간 동안의 급기 온도 데이터를 가져와"

• "로비 구역에 전력을 공급하는 장비는 무엇인가요?"

환경 변수

개발

npm run dev       # watch mode — stdio transport
npm run dev:http  # watch mode — HTTP transport
npm run build     # compile TypeScript
npm start         # run stdio transport
npm run start:http # run HTTP transport

라이선스

MIT