framework-mcp

빠르게 변화하는 프레임워크에 대해 검증되고 버전이 고정된 답변을 코딩 에이전트(Claude Code, Cursor 등)에 제공하는 원격 MCP 서버입니다. 첫 번째 대상은 Expo SDK 54입니다.

이유: LLM 학습 데이터는 프레임워크 릴리스 주기보다 더 빨리 낡습니다. 에이전트들은 검증되고 버전이 고정된 소스를 확인하는 대신 동일한 버전별 질문을 계속 추측합니다. 이 서버가 바로 그 소스입니다.

기술 스택

Node 24 + TypeScript, Streamable HTTP 전송(상태 저장, 연결별 세션)을 통한 @modelcontextprotocol/sdk, Express, Postgres(pg), SDK 자체 requireBearerAuth 미들웨어를 통한 API 키 인증.

호스팅: Railway(컴퓨팅, 월 ~$5 Hobby 플랜) + Neon(Postgres, 무료 티어, 브랜치 가능).

로컬 설정

1. 무료 Neon 계정과 프로젝트를 만듭니다. dev 브랜치의 연결 문자열을 복사합니다.

2. cp .env.example .env를 실행하고 DATABASE_URL(Neon에서)과 API_KEY_PEPPER(긴 임의 문자열 - node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"로 생성)를 채웁니다.

3. 설치, 마이그레이션, 시드, 빌드:

   npm install
   npm run db:migrate
   npm run db:seed
   npm run build

4. API 키를 생성합니다:

   npm run create-api-key -- "my laptop"

   이 명령은 원시 키를 한 번만 출력합니다 - 저장해 두세요. 다시 복구할 수 없습니다.

5. 로컬에서 실행:

   npm run dev

   curl http://localhost:3000/health가 ok를 반환해야 합니다.

MCP Inspector로 검증

npx @modelcontextprotocol/inspector

전송 방식 "Streamable HTTP"로 http://localhost:3000/mcp에 연결하고 연결 설정에서 Authorization: Bearer <your-api-key> 헤더를 설정합니다. 3개의 도구(ping, query_framework_doc, report_outcome)가 모두 나열되고 호출 가능한지 확인합니다.

Railway에 배포

1. curl -fsSL agents.railway.com | sh를 실행한 다음 railway login을 실행합니다.

2. 이 저장소에서: railway init(프로젝트가 이미 있으면 railway link)을 실행합니다.

3. 환경 변수를 설정합니다(대시보드 또는 railway variable set KEY=value): DATABASE_URL(dev 브랜치와 별도인 Neon 프로덕션 브랜치 연결 문자열), API_KEY_PEPPER, NODE_ENV=production.

4. railway up을 실행합니다.

5. Railway 대시보드에서: Settings → Networking → Generate Domain을 선택합니다. PUBLIC_HOSTNAME을 해당 도메인으로 설정합니다(SDK의 DNS 리바인딩 호스트 검사가 실제 트래픽을 허용하는 데 필요).

6. 프로덕션 DATABASE_URL에 대해 npm run db:migrate && npm run db:seed를 한 번 실행합니다(자신의 머신에서 프로덕션 연결 문자열을 가리키며).

7. 프로덕션 DATABASE_URL을 가리키는 npm run create-api-key로 프로덕션 API 키를 생성합니다.

API 키 받기

셀프 서비스: **https://framework-mcp-production.up.railway.app/**를 방문하여 이메일을 입력하면 즉시 키를 받을 수 있습니다(이메일당 활성 키 1개, 속도 제한 있음).

관리자/로컬 대체 방법: npm run create-api-key -- "label".

원격 클라이언트 연결

Claude Code .mcp.json에서:

{
  "mcpServers": {
    "framework-mcp": {
      "type": "http",
      "url": "https://<your-railway-domain>/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

도구

• ping(message) - 상태 확인

• query_framework_doc(framework, version, question) - 검증된 답변 조회, query_id 반환

• report_outcome(query_id, worked, note?) - 반환된 답변이 실제로 작동했는지 기록

상태

db/seed/expo-54.json의 시드 데이터(20개 항목)는 2026-08-21에 https://expo.dev/changelog/sdk-54 및 https://docs.expo.dev/modules/autolinking/에 대해 검증되었습니다.

셀프 서비스 가입은 /에서 운영 중입니다(이메일 → 즉시 API 키, 이메일당 1개, IP 속도 제한). Smithery / Glama / mcp.so에 등록되어 있습니다.

연기됨(Stage B, 아직 구축되지 않음): Stripe 결제, api_keys의 plan_tier / credit_balance / 키별 속도 제한 적용, 기타 프레임워크, 피드백 기반 점수/순위.