framework-mcp

코딩 에이전트를 위한 의존성 최신성 검사 계층: 코딩 에이전트(Claude Code, Cursor 등)에게 빠르게 변화하는 프레임워크(Expo, Next.js, Supabase, Prisma 등 계속 추가 중)에 대한 검증되고 버전이 고정된 답변을 제공하는 원격 MCP 서버입니다.

이유: LLM 학습 데이터는 프레임워크 릴리스 주기보다 더 빨리 구식이 됩니다. 에이전트는 검증되고 버전이 고정된 소스를 확인하는 대신 동일한 버전별 질문을 계속 재추측합니다. 이 서버가 바로 그 소스입니다. 단일 프레임워크 도구가 아니라, 코딩 에이전트가 의존성의 현재 동작에 대해 '기억하는' 것을 신뢰하기 전에 질의할 수 있는 범용 계층입니다.

스택

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

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

Related MCP server: react-native-dev-mcp

로컬 설정

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-rebinding 호스트 검사에 필요).

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) - 상태 확인

• list_frameworks() - 포함된 모든 프레임워크/버전과 항목 수를 나열합니다 - 아래에 전달할 정확한 슬러그/버전을 모르면 먼저 호출하세요

• query_framework_doc(framework, version, question) - 검증된 답변을 조회하고 query_id를 반환합니다

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

적용 범위

모든 항목은 2026-08-22에 db/seed/ 아래 각 시드 파일에 인용된 공식 소스를 기준으로 검증되었습니다. 프레임워크를 추가하려면: 기존 파일의 형식을 따라 새 db/seed/<slug>.json을 만든 다음 npm run db:seed를 실행합니다(해당 폴더의 모든 *.json을 자동으로 가져옵니다).

상태

셀프 서비스 가입은 /에서 운영 중입니다(이메일 → 즉시 API 키, 이메일당 1개, IP 속도 제한). 공식 MCP 레지스트리(registry.modelcontextprotocol.io)에 게시되었고 mcpservers.org와 Glama에 제출되었습니다(둘 다 검토 대기 중). Smithery(해당 OAuth 검색 스캐너는 단순 정적 베어러 키 인증을 지원하지 않음)나 mcp.so(무료 등록 티어 없음)에는 없습니다.

보류됨(Stage B, 아직 구축되지 않음): Stripe 결제, api_keys의 plan_tier / credit_balance / 키별 속도 제한 적용, 피드백에 대한 점수/순위.