MCP Stark Brain (Payments)

로컬 MCP 서버는 일상 업무에서 Payments 팀을 지원합니다:

• Python 마이크로서비스에서 사용하는 아키텍처 패턴을 조회합니다.

• 마이크로서비스 사양(각 서비스의 목적과 책임)을 검색합니다.

• 결제 처리 흐름을 이해합니다.

• 문서 검색과 GCP 분석(Datastore + Cloud Logging / Log Explorer)을 결합하여 CS(Customer Success) 티켓을 분류하고 조사합니다.

• ECDSA 프로젝트 자격 증명을 사용하여 Stark Bank API를 development(기본값) 또는 sandbox(명시적으로 요청된 경우에만)에서 호출합니다.

starkbank/alexandria 문서에 대해 RAG를 수행하고, 개인 키로 Stark Bank API 요청에 서명하며, 사용자 자신의 gcloud ID(ADC)를 사용하여 GCP 쿼리를 실행합니다.

1. 작동 방식

IDE / LLM  --stdio-->  MCP server
                         |-- Docs (RAG): fetch alexandria via GitHub PAT -> local vector index
                         |-- Stark Bank API: ECDSA-signed HTTP to development (default) / sandbox
                         |-- GCP: Datastore + Cloud Logging via your gcloud ADC (project per call)

• 문서는 원격 우선입니다(git clone을 유지하지 않음). 서버는 로컬 임베딩 인덱스를 구축하기 위해 GitHub API를 통해 리포지토리 tarball을 다운로드합니다(전체 콘텐츠에 대해 한 번의 요청). 벡터 인덱스만 로컬에 캐시됩니다.

• 속도 제한 인식. GitHub 예산이 부족해지면 서버는 리포지토리를 클론하고 local 모드로 전환할 것을 제안합니다(섹션 10 참조).

• Stark Bank API는 기본적으로 development (https://development.api.starkbank.com)를 사용합니다. 샌드박스는 명시적 사용자 요청 후 도구가 environment="sandbox"로 호출될 때만 사용됩니다. 프로덕션은 절대 허용되지 않습니다.

• GCP 프로젝트는 호출별로 전달됩니다. 고정 프로젝트 환경 변수는 없습니다. 각 쿼리는 명시적 project를 받으므로 전역 gcloud config를 건드리지 않고 같은 세션에서 마이크로서비스 프로젝트 간에 전환할 수 있습니다.

• GCP에는 서비스 계정 키가 없습니다. GCP 액세스는 개인 ADC 자격 증명을 사용하므로 사용자별 권한과 감사 추적이 보존됩니다.

2. 사전 요구 사항

• Python 3.12(번들 빌드/설치에 필요). chromadb와 fastembed(onnxruntime 경유)는 아직 최신 인터프리터용 사전 빌드 휠을 안정적으로 제공하지 않으므로, 프로젝트는 requires-python = ">=3.11,<3.13"으로 고정하고 아래의 모든 명령은 명시적으로 3.12를 대상으로 합니다. 먼저 버전을 확인하지 않고서는 시스템 기본 python3을 대체하지 마세요.

• uv(권장) 또는 **pipx**로 번들을 설치합니다.

• Google Cloud SDK (gcloud).

uv로 고정된 Python 버전을 확인/설치합니다(시스템 Python에는 영향을 주지 않음):

uv python install 3.12

3. GitHub PAT 생성

각 개발자는 자신의 PAT를 생성합니다(공유하거나 커밋하지 않음). alexandria는 starkbank 조직 소유의 비공개 리포지토리이므로 어떤 토큰 유형이 작동하는지는 조직의 토큰 정책에 따라 다릅니다. 선택하기 전에 아래 두 옵션을 모두 읽어보세요.

옵션 A: fine-grained PAT(먼저 시도)

1. GitHub -> Settings -> Developer settings -> Fine-grained tokens -> 새 토큰 생성.

2. 리소스 소유자: starkbank.

3. 리포지토리 액세스: 선택한 리포지토리만 -> starkbank/alexandria.

4. 권한: 리포지토리 권한 -> Contents: 읽기 전용.

5. 토큰을 생성하고 복사합니다(mcp.json에서 환경 변수로 설정하게 됩니다).

6. https://github.com/settings/personal-access-tokens에서 상태를 확인합니다. 조직에서 승인이 필요하면 Pending으로 표시되고 승인될 때까지 모든 요청에 404 오류가 발생합니다. starkbank 조직 소유자에게 조직의 Settings -> Personal access tokens -> Pending requests에서 승인을 요청하거나 옵션 B로 건너뛰세요.

옵션 B: classic PAT(조직에서 fine-grained 토큰을 승인하지 않을 경우 대체)

Classic PAT는 위의 조직 승인 단계의 적용을 받지 않으므로, 조직에서 fine-grained 토큰을 제한하는 경우 더 빠른 경로입니다.

1. GitHub -> Settings -> Developer settings -> Tokens (classic) -> 새 토큰 생성.

2. 범위: repo (클래식 토큰은 비공개 리포지토리에 대해 contents 전용 범위가 없습니다).

3. starkbank 조직에서 SSO를 적용하는 경우 새로 생성된 토큰 옆의 Configure SSO를 클릭하고 starkbank에 대해 Authorize합니다. 승인되지 않은 토큰은 승인되지 않은 fine-grained 토큰과 마찬가지로 starkbank 리소스에서 404 오류가 발생합니다.

어느 쪽이든, 설치 후에는 토큰에 의존하기 전에 diagnose_github_access 도구를 실행하여(섹션 8) 토큰이 실제로 작동하는지 확인하세요.

4. GCP 인증 (ADC)

gcloud auth login
gcloud auth application-default login

여기서 프로젝트를 설정할 필요가 없습니다. MCP는 각 GCP 도구 호출에서 project를 전달받습니다. analyze_ticket / resolve_project를 사용하여 프로젝트 제안을 받으세요.

5. Stark Bank API 자격 증명 (ECDSA)

API 호출은 정적 API 키가 아닌 ECDSA(secp256k1)로 인증됩니다. 공식 문서: Authentication을 참조하세요.

1. 아직 키 쌍을 생성하지 않았다면 키 쌍을 생성하고 개발 환경에 대해 Web Banking(Integrations → Project)에서 공개 키만 등록합니다.

2. 개인 키 PEM을 사용자 머신에 보관합니다. 커밋하지 말고 공개 키를 이 리포지토리에 넣지 마세요(MCP는 요청 서명에 공개 키가 필요하지 않습니다).

3. 프로젝트를 생성/등록한 후 Web Banking에 표시된 프로젝트 ID를 확인합니다.

4. 환경 변수를 통해 MCP가 PEM 및 프로젝트 ID를 가리키도록 합니다(6단계 / 섹션 11 참조).

개인 키 권장 위치(리포지토리 외부):

mkdir -p ~/.config/mcp-stark-brain
chmod 700 ~/.config/mcp-stark-brain
# copy your privateKey.pem there, then:
chmod 600 ~/.config/mcp-stark-brain/privateKey.pem

기본 Base URL:

6. 번들 빌드 (wheel)

리포지토리 루트에서 인터프리터를 항상 명시적으로 Python 3.12로 고정하세요. PATH에서 우연히 첫 번째로 발견되는 Python에 의존하여 uv build를 그냥 실행하지 마세요.

rm -rf dist  # avoid mixing wheels from a previous version/build
uv build --python 3.12 -o dist

그러면 dist/에 설치 가능한 아티팩트가 생성됩니다(파일 이름의 정확한 버전은 pyproject.toml의 version에서 가져오며, 현재 0.2.0입니다):

dist/
  mcp_stark_brain-0.2.0-py3-none-any.whl
  mcp_stark_brain-0.2.0.tar.gz

.whl을 개발자(또는 공유 위치)에게 배포합니다.

uv가 없는 경우: python3.12 -m venv .venv312로 venv를 만들고 활성화한 다음 pip install build && python -m build -o dist를 실행하세요. 먼저 python3.12 --version으로 확인하세요. 해당 명령이 없으면 계속하기 전에 Python 3.12를 설치하세요. 다른 주/부 버전으로 빌드하지 마세요.

7. IDE에 MCP 설치

휠을 격리된 도구로 설치하되, 도구의 환경이 빌드/테스트된 환경과 일치하도록 다시 Python 3.12를 명시적으로 고정하세요. 버전 번호를 직접 수정하지 않도록(그리고 이전 빌드에서 남은 오래된 휠을 설치할 위험을 피하도록) glob을 사용하세요:

# with uv (recommended)
uv tool install --python 3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

# or with pipx
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

그러면 PATH에 mcp-stark-brain 명령이 노출됩니다.

그런 다음 IDE의 MCP 구성(예: Cursor ~/.cursor/mcp.json 또는 프로젝트 .cursor/mcp.json)에 서버를 추가합니다:

{
  "mcpServers": {
    "stark-brain": {
      "command": "mcp-stark-brain",
      "env": {
        "ALEXANDRIA_GITHUB_PAT": "<your-personal-fine-grained-PAT>",
        "STARKBANK_PRIVATE_KEY_PATH": "/Users/you/.config/mcp-stark-brain/privateKey.pem",
        "STARKBANK_PROJECT_ID": "<your-project-id>",
        "STARKBANK_DEV_BASE_URL": "https://development.api.starkbank.com",
        "STARKBANK_SANDBOX_BASE_URL": "https://sandbox.api.starkbank.com"
      }
    }
  }
}

새 MCP 서버를 인식하도록 IDE를 다시 시작/새로고침합니다.

Tools & MCP 목록의 stark-brain 옆에 사용자 지정 아이콘을 원하시나요(공식 github MCP가 로고를 표시하는 것처럼)? cursor-plugin/README.md에서 이 동일한 구성을 logo가 있는 로컬 Cursor 플러그인으로 패키징하는 선택적 래퍼를 확인하세요. 순전히 외관용입니다. 신경 쓰지 않으면 건너뛰세요.

8. 이미 설치된 MCP 업데이트

이 리포지토리가 변경될 때마다(새 도구, 버그 수정, 구성 기본값 수정 등) 새 번들이 필요합니다. 명령은 원래 설치한 방법에 따라 다릅니다. 잘못된 명령을 사용하는 것이 "내 수정 사항이 왜 안 보이지?" 혼란의 가장 흔한 원인이므로 6단계와 일치하는 명령을 선택하세요:

# 1. Pull the latest source and rebuild the bundle (repo maintainer, or you if you
#    build it yourself). Always clean dist/ first to avoid mixing old/new wheels.
git pull
rm -rf dist
uv build --python 3.12 -o dist

# 2a. If you installed with `uv tool install`, use --reinstall (uv tool upgrade
#     does NOT work for local wheel paths, only for PyPI-published packages):
uv tool install --python 3.12 --reinstall ./dist/mcp_stark_brain-*-py3-none-any.whl

# 2b. If you installed with pipx, uninstall + reinstall (pipx has no local-wheel
#     upgrade command either):
pipx uninstall mcp-stark-brain
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

그런 다음 Cursor가 서버 프로세스를 실제로 다시 생성하게 하세요. 표시되는 도구 목록은 해당 특정 stdio 하위 프로세스가 시작할 때 알린 내용이므로 디스크에 다시 설치하는 것만으로는 업데이트되지 않습니다:

1. 먼저 재설치가 실제로 반영되었는지 확인합니다(Cursor 외부의 일반 터미널에서):

   uv tool list | grep -A2 mcp-stark-brain   # confirm the version bumped
   which mcp-stark-brain

2. Cursor에서 서버를 껐다가 켭니다 — 이는 전체 앱을 종료하지 않고 단일 MCP 서버를 다시 생성하는 공식 지원 방법입니다. Cmd+Shift+J -> Tools & MCP -> stark-brain 찾기 -> 끔으로 전환하고 몇 초 기다린 후 켬으로 전환.

3. 새 채팅을 엽니다. 토글 전에 이미 열려 있던 채팅은 서버가 다시 시작된 후에도 이전 도구 목록을 계속 표시할 수 있습니다.

4. 도구가 여전히 오래된 것처럼 보이면 Cursor의 Shared Process — 앱 인스턴스당 하나의 백그라운드 프로세스로 모든 MCP 하위 프로세스를 호스팅합니다(창별이 아니므로 Developer: Reload Window는 이를 다시 시작하지 않습니다) — 메모리에 이전 하위 프로세스가 아직 살아 있음을 의미합니다. 앱을 완전히 종료(Cmd+Q, 창을 닫는 것만으로는 안 됨)하고 다시 여세요. 그러면 Shared Process와 그와 함께 모든 MCP 하위 프로세스가 종료됩니다.

5. 추측 대신 프로토콜 수준에서 확인하려면: Cmd+Shift+U -> MCP Logs 드롭다운 -> stark-brain -> tools/list 응답에 실제로 새 도구 이름이 포함되어 있는지 확인하세요. 거기에도 없으면 문제는 Cursor의 캐시가 아니라 설치된 번들이므로 1단계로 돌아가세요.

6. 새 도구가 표시되면 status 도구를 실행하여 업데이트가 반영되었는지 확인합니다(docs_mode, repo, ref, embed_model이 기대한 대로 표시되는지 확인).

7. 문서 콘텐츠만 변경된 경우(코드가 아닌 경우) 아무것도 다시 설치할 필요 없이 IDE에서 refresh_docs()를 호출하기만 하면 됩니다.

업데이트 시 PAT를 다시 생성하거나 gcloud auth를 다시 실행할 필요가 없습니다. 해당 자격 증명은 설치된 버전과 무관합니다.

9. 첫 실행 및 사용

• 첫 docs 도구 호출에서 서버가 alexandria 콘텐츠를 가져와 로컬 인덱스를 구축합니다(임베딩 모델이 한 번 다운로드되는 동안 시간이 걸릴 수 있음).

• 문서 변경 후 refresh_docs를 사용하여 다시 동기화합니다(증분: 변경된 파일만 다시 임베딩됨).

• status는 docs 모드, 인덱스된 파일 수, 속도 제한 및 Stark Bank API 자격 증명 구성 여부(starkbank_api_configured)를 보고합니다.

• Stark Bank API 도구는 기본적으로 development를 사용합니다. 사용자가 명시적으로 샌드박스를 요청한 경우에만 environment="sandbox"를 전달하세요.

사용 가능한 도구:

10. 원격 vs 로컬 모드

• remote (기본값): 문서는 GitHub에서 PAT를 통해 가져옵니다. 효율적이지만(tarball = 새로고침당 1회 요청), GitHub API 할당량을 소모합니다.

• local: 직접 클론한 디렉터리에서 문서를 읽습니다. API 사용량 0입니다.

GitHub rate limit이 거의 소진되면 서버가 경고하고 전환을 제안합니다. 전환하는 방법:

# clone the repo once (your own credentials)
git clone git@github.com:starkbank/alexandria.git ~/repos/alexandria

그런 다음 mcp.json에 설정하거나:

"env": {
  "ALEXANDRIA_GITHUB_PAT": "<pat>",
  "STARK_BRAIN_DOCS_MODE": "local",
  "STARK_BRAIN_DOCS_PATH": "/Users/you/repos/alexandria"
}

또는 도구를 통해 런타임에 전환합니다:

set_docs_source(mode="local", path="/Users/you/repos/alexandria")
refresh_docs()

11. 구성 참조(환경 변수)

.env.example을 참조하세요.

12. 문제 해결

• configuration error: ALEXANDRIA_GITHUB_PAT is required — mcp.json 환경에 PAT를 설정하거나 local 모드로 전환하세요.

• GitHub 401 — PAT가 유효하지 않거나 만료되었습니다. 다시 생성하세요.

• GitHub 404 ("Repo or ref not found")가 저장소가 존재하는데도 발생하는 경우 — 프라이빗 저장소의 경우 GitHub는 리소스가 실제로 존재하지 않을 때와 토큰이 해당 리소스를 볼 수 없을 때 모두 404를 반환하므로, 이는 거의 항상 ALEXANDRIA_REPO/ALEXANDRIA_REF가 잘못된 것이 아니라 토큰/액세스 문제입니다. 가장 흔한 원인은 조직 관리자 승인이 아직 보류 중인 세분화된 PAT입니다. (https://github.com/settings/personal-access-tokens 확인 — "Pending"으로 표시되면 승인 절차 또는 클래식 PAT 대체 방법은 섹션 3을 참조하세요.) diagnose_github_access()를 실행하면 이 문제를 정확히 짚어주는 실시간 확인이 가능합니다.

• GitHub 403 / rate limited — PAT 권한을 확인하거나, 클론한 후 local 모드를 사용하세요.

• GCP credentials not found — gcloud auth application-default login을 실행하세요.

• Datastore/Logging 권한 오류 — 액세스 권한이 없는 프로젝트를 쿼리한 경우입니다. 다른 project를 선택하거나 액세스를 요청하세요.

• 첫 실행 시 모델 다운로드가 느린 경우 — 임베딩 모델은 첫 사용 후 STARK_BRAIN_CACHE_DIR 아래에 캐시됩니다.

• 재설치 후 새로 추가한 도구가 표시되지 않는 경우 — 이는 잘못된 설치가 아니라 Cursor 측의 오래된 프로세스 때문입니다(단계별 내용은 섹션 8 참조). 실행 중인 MCP 하위 프로세스는 디스크의 재설치를 스스로 인식하지 못합니다. Tools & MCP에서 서버를 껐다 켜고, 새 채팅을 연 다음, 그래도 부족하다면 Cursor를 완전히 종료(Cmd+Q)했다가 다시 여세요.

• STARKBANK_PRIVATE_KEY_PATH is not set / API 도구 오류 — mcp.json에서 PEM의 절대 경로와 STARKBANK_PROJECT_ID를 설정하세요(섹션 5 참조). status().starkbank_api_configured가 true인지 확인하세요.

• Stark Bank API 401 / 잘못된 서명 — 잘못된 프로젝트 ID, 해당 환경에 등록되지 않은 PEM, 또는 시계 오차입니다. 공개 키가 해당 Web Banking 환경(개발 vs 샌드박스)에 등록되어 있는지 확인하세요.

13. 보안 참고 사항

• 사용자 PAT는 Authorization 헤더에만 전송되며 절대 기록되지 않습니다.

• Stark Bank 개인 키는 요청 시점에 디스크에서 읽히며 절대 기록되지 않습니다.

• 서비스 계정 키는 배포되지 않습니다. GCP 액세스는 사용자 개인 ADC 자격 증명입니다.

• GCP project는 호출마다 전달됩니다 — 공유되거나 하드코딩된 프로젝트가 없습니다.

• 클라이언트는 프로덕션 Stark Bank API 호스트를 거부합니다.

• .env, *.pem, keys/ 및 로컬 캐시는 git에서 무시됩니다.

14. 개발

소스 파일은 src/ 아래에 평평하게 있습니다. (추가 src/mcp_stark_brain/ 중첩 없음)

pyproject.toml의 빌드 설정은 이 파일들을 휠에서 mcp_stark_brain import 패키지로 제공합니다(packages = ["src"] + sources = {"src" = "mcp_stark_brain"}). 따라서 디스크 레이아웃과 관계없이 진입점과 내부 import는 변경되지 않습니다.

이 이름 변경은 editable/dev-mode 설치와 호환되지 않으므로(hatchling/pip 제한) uv sync는 tool.uv.package = false로 구성됩니다. 즉, 프로젝트 자체가 아닌 의존성만 설치합니다. conftest.py와 scripts/smoke_test.py는 devtools/bootstrap.py를 사용하여 테스트와 로컬 스크립트에서 import mcp_stark_brain이 src/를 직접 참조하도록 만들며, 설치 단계가 필요 없습니다.

uv python install 3.12
uv sync --extra dev --python 3.12
uv run ruff check .
uv run pytest
uv run python scripts/smoke_test.py

서버를 실제로 로컬에서 사용해 보려면(휠 빌드 불필요):

uv run --python 3.12 python -c "from devtools.bootstrap import ensure_importable; ensure_importable(); from mcp_stark_brain.server import main; main()"