Cartesi 지식 MCP 서버

PostgreSQL에서 엄선된 Cartesi 개발자 리소스를 스트리밍 가능한 HTTP를 통해 AI 에이전트에 노출하는 프로덕션 지향 Model Context Protocol 서버입니다.

현재 기능

• streamable_http_app()을 사용하는 FastMCP (mcp[cli] 1.26.x) — 세션 수명이 올바르게 실행되도록 프로덕션에서 FastMCP의 Starlette 앱을 직접 사용합니다(src/main.py의 create_app() 참조).

• 지식 데이터베이스에 대한 읽기 전용 액세스를 위한 비동기 SQLAlchemy + asyncpg.

• 계층화된 레이아웃: 구성 및 로깅(src/core/), DB 세션 및 모델(src/db/), 리포지토리, 도메인 서비스(src/domain/resource_service.py), 스키마, 포맷터 및 src/server/ 하위의 서버 모듈.

• 전송 보안: src/server/server.py의 DNS 리바인딩 보호 및 구성 가능한 allowed_hosts / allowed_origins(배포 호스트 이름에 맞게 확장).

• 일반 HTTP 상태 확인: MCP 경로와 함께 GET /healthz는 {"status":"ok"}를 반환합니다.

지식 응답은 메타데이터 및 링크(제목, URI, canonical_url, 문서 경로)입니다. 여기에는 전체 가져온 페이지 본문이 포함되지 않습니다. 에이전트는 원시 HTML 또는 마크다운이 필요할 때 외부 URL을 가져와야 합니다.

워크플로우 도구(prepare_cartesi_*, send_input_to_application, prepare_*_deposit_instructions, get_cartesi_app_logic_guidance)는 사용자의 컴퓨터를 위한 지침 및 명령 템플릿만 반환합니다. 이 서버에서 Cartesi CLI, cast 또는 체인 RPC를 직접 실행하지 않습니다.

요구 사항

• Python ≥ 3.11 (pyproject.toml 참조; 포함된 Dockerfile은 Python 3.12를 사용합니다).

• src/db/models.py 및 ResourceService에서 예상하는 엄선된 리소스 스키마로 채워진 PostgreSQL 데이터베이스.

환경 변수

.env.example을 .env로 복사하고 조정하십시오. 기본값 및 필드 이름은 src/core/config.py에 정의되어 있습니다(특히 DATABASE_URL, APP_HOST, APP_PORT, MCP_BASE_URL, 페이지네이션 제한).

설치

uv 사용(권장):

uv sync

pip 사용:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

실행

python -m src.main

uv run python -m src.main

uv run uvicorn src.main:create_app --factory --host 0.0.0.0 --port 8000

MCP 엔드포인트는 다음의 스트리밍 가능한 HTTP입니다:

• http://<host>:<port>/mcp (기본값: http://0.0.0.0:8000/mcp)

Docker

이 리포지토리에는 uv로 종속성을 설치하고 python -m src.main을 실행하는 다단계 Dockerfile이 포함되어 있습니다. 런타임에 DATABASE_URL 및 기타 환경 변수를 설정하십시오(예: -e 또는 오케스트레이터를 통해).

제안된 클라이언트 테스트

MCP Inspector 또는 MCP 호환 클라이언트를 사용하고 다음 주소에 연결하십시오:

http://localhost:8000/mcp

MCP 리소스

MCP 도구 (등록된 이름)

이들은 클라이언트가 보는 name= 값입니다(Python 핸들러 이름은 다를 수 있음).

지식

• summarize_knowledge_base — 범위, 개수, 방향성

• get_knowledge_taxonomy — 알려진 태그 및 소스 제목

• search_knowledge_resources — 쿼리, 태그, 소스, 종류별 검색

• get_resource_detail — ID별 리소스 하나, 선택적 경로

• list_resource_doc_routes — 문서 리소스에 대한 경로

• search_documentation_routes — 리소스 전반의 경로 검색

• list_resources_for_tag / list_resources_for_source

• get_repository_sync_status

• build_debugging_context — 문제 중심의 리소스 및 경로 번들

호스트 측 Cartesi 워크플로우 (지침만)

• prepare_cartesi_create_command — 안정적인 v1.5.x 대 알파 v2.0 생성 가이드

• prepare_cartesi_build_command

• prepare_cartesi_run_command

• send_input_to_application — InputBox + cast 템플릿

• prepare_erc20_deposit_instructions — ERC20Portal 흐름

• prepare_erc721_deposit_instructions — ERC721Portal 흐름

• prepare_erc1155_deposit_instructions — ERC1155SinglePortal 흐름

• get_cartesi_app_logic_guidance — 주소록, 포털, 바우처, 공지, 보고서

MCP 프롬프트

• debug_cartesi_issue — 엄선된 지식을 사용한 구조화된 디버깅

• find_cartesi_docs — 주제에 대한 문서 경로 발견

• explain_repository_context — 리포지토리 리소스 + 상태 요약