kompa-mcp-server

Kompa 소셜 리스닝 데이터(버즈, 감성 분석, 트렌드라인, 핫 토픽, 고유 작성자)를 모든 MCP 클라이언트가 호출할 수 있는 도구로 노출하는 MCP(Model Context Protocol) 서버입니다. 독립형 채팅 UI 대신 Claude(Desktop 또는 Code) 안에서 Kompa 데이터에 대해 직접 대화할 수 있도록 만들어졌습니다.

이 패키지는 kompa-chat Next.js 앱과 독립적입니다. 동일한 Kompa GraphQL API와 로그인 흐름만 재사용하며, 일반 MCP 서버로 포팅된 것입니다. 두 개의 진입점을 제공합니다:

• build/index.js — stdio 전송 방식. 하위 프로세스를 생성하는 로컬 MCP 클라이언트(로컬 설정을 통한 Claude Desktop/Code)용입니다.

• build/http.js — Streamable HTTP 전송 방식, 멀티 테넌트: 호스팅된 커넥터 URL 하나로 여러 고객을 서비스할 수 있습니다. 전체 VPS 배포 가이드(systemd + Caddy + 고객 온보딩)는 DEPLOY.md를 참조하세요.

계정 및 토픽 설정

별도의 API 키 시스템은 없습니다. 각 고객은 이미 Kompa 사용자 이름/비밀번호를 보유하고 있으며, 여기서도 도구 호출을 통해 동일한 자격 증명을 사용합니다:

configure_account({ username, password, topicIds: ["topic-id-1", ...] })

대화 시작 시 한 번 호출하세요(자격 증명/토픽을 언급하면 Claude가 자동으로 호출하거나, 명시적으로 요청할 수 있습니다). 이후 다른 모든 도구는 configure_account를 다시 호출할 때까지 해당 계정과 topic_ids를 재사용합니다 — 매 호출마다 반복할 필요는 없지만, 호출별로 topicIds를 전달하여 재정의할 수는 있습니다.

이 방식은 헤더 기반 인증 대신 사용됩니다. Claude 커넥터의 사용자 지정 요청 헤더가 현재 게이트 베타(gated beta)로 배포 중이기 때문입니다. 자세한 내용은 DEPLOY.md의 "Auth model" 참고 사항을 확인하세요.

stdio 진입점의 경우 KOMPA_USERNAME/KOMPA_PASSWORD/KOMPA_DEFAULT_INDEXES 환경 변수를 설정하면 도구 호출을 완전히 건너뛸 수 있습니다. 이 경우 계정이 시작 시 미리 구성됩니다.

도구

모든 데이터 도구는 fromDate/toDate("YYYY-MM-DD HH:mm:ss"), 선택적 types, query, sentiments, 선택적 topicIds(기본값은 configure_account로 설정된 topicIds로 대체)를 허용합니다.

설정

npm install
npm run build

참고용으로 .env.example을 복사하세요(stdio 진입점에만 관련됨 — 위 참조).

게시 전 독립 실행

빌드된 진입 파일을 모든 MCP 클라이언트에 직접 지정하세요:

{
  "mcpServers": {
    "kompa": {
      "command": "node",
      "args": ["/absolute/path/to/kompa-mcp-server/build/index.js"]
    }
  }
}

• Claude Desktop: claude_desktop_config.json(설정 → 개발자 → 구성 편집)에 이 블록을 넣으세요.

• Claude Code: 프로젝트 루트의 .mcp.json에 동일한 mcpServers 블록을 넣거나, 다음을 실행하세요:

  claude mcp add kompa -- node /absolute/path/to/kompa-mcp-server/build/index.js

구성 편집 후 클라이언트를 다시 시작하고, 채팅에서 *"제 Kompa 계정은 X/Y, 토픽 ID는 Z입니다. 'foo' 쿼리에 대한 감성 분포를 2026-08-01부터 2026-08-21까지 알려주세요"*와 같이 말하세요. Claude가 configure_account를 호출한 다음 데이터 도구를 호출합니다.

npm에 게시

사용자가 로컬 경로 대신 npx kompa-mcp-server로 설치할 수 있도록:

npm login
npm publish --access public

그러면 MCP 구성은 다음과 같아집니다:

{
  "mcpServers": {
    "kompa": {
      "command": "npx",
      "args": ["-y", "kompa-mcp-server"]
    }
  }
}

Claude Code 플러그인 마켓플레이스에 게시

Claude Code와, Team/Enterprise 조직의 경우 claude.ai 자체도 git 저장소에서 직접 플러그인 마켓플레이스를 추가할 수 있습니다. 여기서는 npm 게시가 필요 없습니다. marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json이 로컬 패키지가 아닌 호스팅된 HTTP 커넥터를 가리키기 때문입니다(DEPLOY.md 참조). 레이아웃:

marketplace-example/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── kompa-mcp/
        └── .claude-plugin/
            └── plugin.json      # edit the connector URL in here first

유지관리자로서:

1. marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json의 url을 실제 배포 도메인(https://mcp.yourdomain.com/mcp)으로 편집하세요.

2. marketplace-example/ 레이아웃을 포함하는 저장소(폴더 이름을 원하는 저장소 루트로 변경)를 GitHub에 푸시하세요. 공개 또는 조직에서만 필요하다면 비공개로 설정하세요(비공개인 경우 설치하는 모든 사람이 GitHub/git 자격 증명을 통해 저장소 접근 권한이 있어야 함).

3. 저장소 URL을 공유하세요.

설치하는 Claude Code 사용자로서:

/plugin marketplace add https://github.com/<you>/<marketplace-repo>
/plugin install kompa-mcp-plugin@<marketplace-name>

claude.ai Team/Enterprise 조직(CLI 없음, GUI 전용):

1. 조직 소유자: Organization settings → Connectors/Plugins → Add plugin marketplace → "Add from a repository" → 동일한 GitHub URL을 붙여넣으세요.

2. 구성원: Customize → Plugins에서 마켓플레이스에 나열된 kompa-mcp-plugin을 찾아 설치/연결을 클릭하세요.

조직이 없는 개인 Free/Pro/Max 계정의 경우 이 저장소 기반 마켓플레이스 경로는 사용할 수 없습니다. 대신 PLUGIN.md의 zip 업로드 흐름을 사용하세요.

참고 사항 / 제한 사항

• 로그인은 kompa-chat의 auth.ts와 동일한 사용자 이름+비밀번호 흐름을 사용합니다 — OAuth 없음, 브라우저 자동화 없음.

• 액세스 토큰은 프로세스 내에서 사용자 이름별로 캐시되며 만료 5분 전에 갱신됩니다.

• topicIds는 계정이 접근할 수 있는 유효한 Kompa 프로젝트 인덱스 ID여야 합니다. 이 서버는 해당 ID를 자동으로 검색하거나 나열하지 않습니다.

• HTTP 모드에서 계정/토픽 구성은 해당 MCP 세션의 메모리에만 존재합니다. 대화/세션을 닫으면 사라지며, 다음 세션에서 configure_account를 다시 호출해야 합니다.