Chakudya MCP Server

MCP(모델 컨텍스트 프로토콜) 서버로, Chakudya Nutrition Registry (CNR) API를 MCP 도구 집합으로 노출하여 MCP 호환 클라이언트(Claude, Claude Code, 기타 LLM 에이전트)가 말라위 식품 데이터를 검색하고, 임상 영양 조회를 실행하며, RAG 지식 기반을 직접 쿼리할 수 있게 합니다.

이것은 새롭고 별개의 계층입니다. 기존 Chakudya Worker를 대체하거나 수정하지 않습니다. 기존 API 앞에 위치하는 작은 Node/TypeScript HTTP 서비스로, MCP 도구 호출을 Worker가 이미 제공하는 라우트에 대한 일반 HTTP 요청으로 변환합니다.

MCP Client (Claude, etc.)
        │  Streamable HTTP (JSON-RPC over HTTP + SSE)
        ▼
Chakudya MCP Server  (this project)
        │  plain HTTPS fetch()
        ▼
Chakudya Worker API  (unchanged) → Supabase / Cohere / Groq / USDA / OFF / FatSecret

별도 서버를 사용하는 이유: Worker가 아닌 이유

공식 MCP TypeScript SDK의 StreamableHTTPServerTransport는 Node의 http.IncomingMessage/ServerResponse를 위해 만들어졌습니다. Cloudflare Workers는 대신 Fetch API를 사용하며, SDK의 웹 표준 변형(WebStandardStreamableHTTPServerTransport)은 더 새롭고 프로덕션 세션 관리에 대해 덜 검증되었습니다. 이를 일반 Node 서비스(Docker, Render, Fly.io, VPS 등)로 실행하는 것이 오늘날 더 표준적이고 문서화가 잘 된 경로이며, 이 문제를 Worker 배포 주기에서 완전히 분리할 수 있습니다. 나중에 단일 플랫폼 배포를 원한다면 Workers에서 웹 표준 전송으로 포팅하는 것을 막을 수 없습니다. src/tools/*의 도구 로직은 어떤 전송이 이를 감싸는지 신경 쓰지 않습니다.

Related MCP server: mealie-mcp

도구

31개 도구 모두 HTTPS를 통해 기존 Chakudya Worker를 호출하거나 순수한 인프로세스 계산/테이블 조회입니다. 어느 것도 Supabase, Cohere, Groq를 직접 건드리지 않으며, ADMIN_API_KEY가 필요하지 않습니다(사용하는 모든 라우트는 공개입니다).

disease_information과 medicine_information은 항상 답변과 함께 교육용 면책 고지를 반환하며 진단/처방 언어를 피하도록 프롬프트됩니다. 그러나 이것들은 여전히 RAG 지식 기반에 있는 내용에 근거한 LLM 생성 텍스트이지 검증된 의학 참고 자료가 아닙니다. 나머지 RAG 기반 도구와 마찬가지로 학습자를 위한 출발점으로 취급하십시오.

pediatric_* 도구(출처: BND 415 Clinical Nutrition — Paediatric Medicine Resources)와 iom_dri_eer_calculator/met_activity_energy_calculator/alcohol_kcal_calculator/respiratory_quotient_interpreter(출처: Nelms/Ireton-Jones, Nutrition Therapy and Pathophysiology, 2장)는 순수 계산/조회 도구입니다. 네트워크 호출이 없고 CNR 데이터 의존성도 없습니다. 추정 전용이라는 동일한 주의 사항이 적용됩니다: 개별화된 임상 평가나 측정된 간접 열량측정을 대체하지 않습니다.

프로젝트 구조

src/
├── index.ts                 Express app, Streamable HTTP session wiring, graceful shutdown
├── config/env.ts            Zod-validated environment config, loaded once at startup
├── clients/chakudyaClient.ts  Fetch wrapper for the Chakudya Worker (GET/POST, error normalization)
├── server/
│   ├── createServer.ts      Builds one McpServer instance and registers all tool modules
│   └── security.ts          Bearer auth + per-IP rate limiting for this server's /mcp endpoint
├── tools/
│   ├── foodTools.ts
│   ├── clinicalTools.ts
│   ├── ragTools.ts
│   ├── educationTools.ts
│   ├── pediatricTools.ts        Pediatric fluid/energy/protein/growth/enteral-feed calculators
│   └── energyExpenditureTools.ts  IOM/DRI EER, MET activity, alcohol kcal, RQ interpreter
│   └── whoGrowthTools.ts        WHO Child Growth Standards z-score/percentile calculator (LMS)
├── data/
│   └── who/                     WHO Child Growth Standards LMS tables (JSON, per standard+sex)
└── utils/
    ├── logger.ts             Structured JSON logging
    └── toolResult.ts         Consistent success/error shaping for every tool handler

환경 변수

.env.example을 .env로 복사한 뒤 채우세요:

보안 고려 사항

• 프로덕션에서는 인증이 필수입니다. env.ts는 NODE_ENV=production이고 MCP_AUTH_TOKEN이 설정되지 않은 경우 시작 시 프로세스를 종료합니다. 이는 단순한 경고가 아니라 의도적인 fail-closed(실패 시 차단) 검사입니다.

• 이 서버는 요청률이 제한된 RAG 라우트 앞에 위치합니다. Worker의 /rag/ask는 IP당 분당 15회로 제한되어 있습니다. 하지만 이는 Worker가 보는 클라이언트 IP 기준이며, 배포 후에는 이 서버의 IP가 그 기준이 되어 모든 사용자가 공유하게 됩니다. MCP 수준의 요청률 제한기 (MCP_RATE_LIMIT_PER_MIN)는 잘못 동작하는 MCP 클라이언트 하나가 다른 모든 사용자의 예산을 조용히 소진하지 못하게 하기 위해 존재합니다. 동시에 여러 MCP 클라이언트가 예상된다면 값을 낮추세요.

• 관리자 키는 내장되어 있지도, 요구되지도 않습니다. 모든 도구는 공개 CNR 라우트를 호출합니다. 나중에 관리자 전용 도구를 추가한다면 CHAKUDYA_ADMIN_API_KEY를 서버 측에만 유지하세요. MCP 클라이언트에 절대 노출하지 마세요.

• 세션 상태는 프로세스 내 메모리에 저장됩니다. 단일 인스턴스에는 문제없습니다. 나중에 로드 밸런서 뒤에서 여러 인스턴스로 확장한다면, 고정 세션(sticky sessions)을 활성화하거나(Mcp-Session-Id 기준 라우팅) src/index.ts의 transports 맵을 공유 저장소로 교체하세요.

• CORS는 기본적으로 꺼져 있습니다. 특정 브라우저 기반 MCP 클라이언트가 있는 경우에만 MCP_ALLOWED_ORIGINS를 활성화하세요. 서버 간 MCP 클라이언트(Claude Desktop, Claude Code 등)는 이 설정이 필요 없습니다.

로컬에서 실행하기

cd ~
git clone https://github.com/edisontaimu9-ui/chakudya-mcp-server.git
cd chakudya-mcp-server
cp .env.example .env
# edit .env: set MCP_AUTH_TOKEN to a long random string
npm install
npm run build
npm start

또는 자동 리로드가 포함된 반복 개발용:

npm run dev

헬스 체크: curl http://localhost:8787/health

MCP 클라이언트 연결하기

Streamable-HTTP를 지원하는 모든 MCP 클라이언트를 다음 주소로 연결하세요:

POST/GET/DELETE  https://<your-deployed-host>/mcp
Header: Authorization: Bearer <MCP_AUTH_TOKEN>

Claude Desktop / Claude Code의 경우, 해당 URL을 가리키는 원격 MCP 서버로 추가하고 동일한 bearer 토큰을 사용하세요. 정확한 구성 파일 구문은 시간이 지나면서 변경되었으므로 Anthropic의 최신 문서를 확인하세요. 최신 mcpServers 원격 서버 형식은 https://docs.claude.com에서 확인할 수 있습니다.

배포: Render(권장 — 무료, 신용카드 불필요)

이 저장소에는 render.yaml이 포함되어 있어, Render의 Blueprint 기능이 대시보드에서 수동으로 구성할 필요 없이 배포를 처리합니다.

1. 이 저장소를 GitHub에 푸시하세요(아래 명령어).

2. Render 대시보드에서: New → Blueprint, GitHub 계정을 연결하고 chakudya-mcp-server 저장소를 선택하세요. Render가 render.yaml을 자동으로 읽습니다.

3. Render가 Free 플랜으로 서비스를 프로비저닝하고 임의의 MCP_AUTH_TOKEN을 자동 생성합니다 (generateValue: true 사용). 첫 배포 후 서비스의 Environment 탭에서 생성된 토큰을 복사하세요. MCP 클라이언트 구성에 필요합니다.

4. 배포하세요. MCP 엔드포인트는 https://<your-service-name>.onrender.com/mcp가 됩니다(실제 생성된 URL은 Render 대시보드에서 확인하세요. 선택한 이름이 이미 사용 중이면 임의의 접미사가 포함될 수 있습니다).

무료 플랜의 절전 문제와 해결 방법

Render의 무료 웹 서비스는 트래픽이 15분간 없으면 종료되고, 다음 요청 시 깨어나는 데 30-60초가 걸립니다. 헬스 체크에는 문제없지만, 클라이언트가 대화 중간에 너무 오래 조용해지면 진행 중인 MCP 세션이 끊어질 수 있습니다(세션 상태는 메모리에 저장됨 — src/index.ts 참조).

해결 방법: 무료 업타임 모니터가 5-10분마다 /health를 핑하여 서비스를 유지하세요.

1. uptimerobot.com에 가입하세요(무료 플랜, 카드 불필요).

2. 새 HTTP(s) 모니터를 추가하세요:

   • URL: https://<your-service>.onrender.com/health

   • 간격: 5분

3. 저장하세요. /health는 의도적으로 인증이 없도록 설계되어, 이 모니터가 MCP_AUTH_TOKEN을 필요로 하지 않습니다.

이렇게 하면 무료 플랜의 월 750시간 한도 내에서 서비스를 24/7 유지할 수 있습니다(이 방식으로 핑하는 서비스 하나에는 한도에 훨씬 미치지 않음).

코드 변경 후 업데이트

연결된 브랜치에 푸시할 때마다 Render가 자동으로 재배포합니다. 추가 단계가 필요 없습니다:

git add .
git commit -m "Update MCP server"
git push

Render 대시보드의 Events 탭에서 배포를 확인하세요. 이 규모의 프로젝트는 보통 1-2분 안에 완료됩니다.

기타 배포 옵션

어디서든 Docker

docker build -t chakudya-mcp-server .
docker run -d -p 8787:8787 \
  -e NODE_ENV=production \
  -e MCP_AUTH_TOKEN=<long-random-string> \
  -e CHAKUDYA_API_BASE_URL=<your-chakudya-worker-url> \
  --name chakudya-mcp chakudya-mcp-server

프로세스 매니저가 있는 일반 VPS

npm install --omit=dev
npm run build
npx pm2 start dist/index.js --name chakudya-mcp

HTTPS를 처리하는 다른 프런트가 없다면 Nginx/Caddy 뒤에 두어 TLS 종료를 처리하세요.

명령줄로 업데이트하기

cd ~
# first time only:
git clone https://github.com/edisontaimu9-ui/chakudya-mcp-server.git
cd chakudya-mcp-server

# after any file update:
cp <path-to-updated-file>.ts src/<path>/<updated-file>.ts
git add .
git commit -m "Update MCP server"
git push

그런 다음 선택한 플랫폼에서 재배포하세요(Render/Railway/Fly는 GitHub 저장소를 연결했다면 푸시 시 자동 재배포합니다. 그렇지 않으면 수동 재배포를 트리거하거나 호스트에서 위의 Docker/pm2 명령어를 다시 실행하세요).