Pharus MCP
Pharus MCP
Pharus 생태계의 조사 서비스를 통합적으로 검색하고 쿼리하기 위한 Python 기반 MCP(Model Context Protocol) 서버입니다. 분리된 서비스 아키텍처를 통해 RIF, SIMBA, Telefônica, Telemática, KYT 및 그래프 분석을 위한 전문 도구를 제공합니다.
주요 기능
서비스 검색: 메타데이터 및 사용 예시가 포함된 조사 서비스의 의미론적 카탈로그
MCP 프로토콜: HTTP Streamable을 통한 Model Context Protocol의 완전한 구현
다양한 데이터 소스: RIF, SIMBA, Telefônica, Telemática, KYT 및 그래프와의 통합
금융 분석: 거래 및 자금 흐름 조사를 위한 전문 분석 도구
그래프 알고리즘: 그래프 메타데이터를 기반으로 자동 알고리즘 제안을 제공하는 의미론적 카탈로그
자동 문서화: 접근 가능한 HTTP 경로를 갖춘 Swagger UI 및 OpenAPI
유연한 구성: 환경 변수 및 서비스별 설정 지원
사전 요구 사항
Python 3.12+
pip (Python 패키지 관리자)
PowerShell 5.1+ (Windows의 경우) 또는 bash (Linux/macOS의 경우)
업스트림 서비스: RIF, SIMBA, Telefônica, Telemática, KYT, Grafos (필요에 따라)
설치
1. 가상 환경 설정
가상 환경(virtualenv)을 생성하고 활성화합니다:
python -m venv .venv
.\.venv\Scripts\Activate.ps1Linux/macOS의 경우:
python3 -m venv .venv
source .venv/bin/activate2. 의존성 설치
python -m pip install --upgrade pip
python -m pip install -e .[dev]3. 환경 변수 설정
예제 파일을 복사합니다(선택 사항):
Copy-Item .env.example .env환경에 맞춰 .env 파일의 서비스 기본 URL을 수정합니다:
HOST=127.0.0.1
PORT=8000
LOG_LEVEL=INFO
GRAFO_API_URL=http://localhost:8001
RIF_API_URL=http://localhost:8082
SIMBA_API_URL=http://localhost:8003
TELEFONICA_API_URL=http://localhost:8004
TELEMATICA_API_URL=http://localhost:8005
KYT_API_URL=http://localhost:8006구성
지원되는 환경 변수:
변수 | 설명 | 기본값 |
| 서버 바인딩 IP 주소 |
|
| HTTP 포트 |
|
| 로그 레벨 (DEBUG, INFO, WARNING, ERROR) |
|
| 그래프 서비스 기본 URL |
|
| RIF 서비스 기본 URL |
|
| SIMBA 서비스 기본 URL |
|
| Telefônica 서비스 기본 URL |
|
| Telemática 서비스 기본 URL |
|
| KYT 서비스 기본 URL |
|
| MCP 프로토콜용 HTTP 경로 |
|
| HTTP 문서 경로 |
|
실행
MCP 서버 시작 (HTTP 경유)
방법 1: Python 모듈 사용 (권장)
.\.venv\Scripts\python -m pharus_mcp --transport http --host 127.0.0.1 --port 8000방법 2: 시작 스크립트 사용
.\.venv\Scripts\python .\scripts\start_server.py방법 3: 바로가기 사용 (-e .[dev] 설치 후)
pharus-start-server업스트림 서비스 관리
RIF, SIMBA, Telefônica, Telemática, KYT 및 Grafos 시작:
.\.venv\Scripts\python .\scripts\start_services.py기본 60초 타임아웃으로 서비스 시작을 대기합니다.
프로세스를 시작하지 않고 연결 확인:
.\.venv\Scripts\python .\scripts\start_services.py --check-only사용자 지정 타임아웃 및 엄격 모드 설정:
.\.venv\Scripts\python .\scripts\start_services.py --timeout 90 --strict모든 서비스 중지 (Windows):
.\.venv\Scripts\python .\scripts\stop_services.py종료하지 않고 PID 나열 (dry-run):
.\.venv\Scripts\python .\scripts\stop_services.py --dry-run서버 접속
사용 가능한 HTTP 경로
MCP 프로토콜은 /mcp 엔드포인트에서 실행됩니다(브라우저 친화적이지 않음). 검사 및 유효성 검사를 위해 다음을 사용하세요:
경로 | 설명 |
|
|
| 서버 상태 확인 |
| 대화형 Swagger UI |
| 전체 OpenAPI 사양 |
| 조사 서비스 카탈로그 |
| 등록된 MCP 도구 목록 |
| MCP 프롬프트 목록 |
| 의미론적 리소스 목록 |
| 특정 리소스의 내용 |
| MCP 엔드포인트 (HTTP 기반 MCP 프로토콜) |
예시:
# Health check
curl http://127.0.0.1:8000/health
# Catálogo de serviços
curl http://127.0.0.1:8000/docs/services
# Detalhe de um serviço (RIF)
curl 'http://127.0.0.1:8000/docs/resource?uri=pharus://services/rif'서비스 카탈로그
사용 가능한 서비스
Grafo - 사례 그래프, 레이블, KYT 및 알고리즘을 사용한 관계 분석
KYT - 문서, 이메일 및 전화번호를 통한 인물 정보 강화
RIF - 거래 및 통계가 포함된 금융 정보 보고서 분석
SIMBA - 은행 계좌 및 거래 내역 조회
Telefônica - CDR, 위치 및 번호 이동성을 사용한 통신 분석
Telemática - 메신저 앱 및 연락처 분석
각 서비스는 전문 도구 세트와 권장 사용법이 담긴 의미론적 카탈로그를 제공합니다.
개발
프로젝트 구조
pharus-mcp/
├── src/pharus_mcp/
│ ├── adapters/ # Adaptadores para serviços upstream (RIF, SIMBA, etc.)
│ ├── catalog/ # Catálogo semântico de serviços e algoritmos
│ ├── config/ # Configuração e settings
│ ├── models/ # Modelos de dados (Pydantic)
│ ├── server/ # Servidor FastAPI e registro MCP
│ ├── app.py # Aplicação FastAPI principal
│ ├── cli.py # Interface de linha de comando
│ ├── commands.py # Comandos e orquestração
│ └── __main__.py # Ponto de entrada
├── tests/ # Suite de testes
├── scripts/ # Scripts auxiliares de inicialização
├── pyproject.toml # Configuração Poetry/pip
└── README.md # Este arquivo테스트 실행
.\.venv\Scripts\python -m pytest상세 출력(verbose) 모드:
.\.venv\Scripts\python -m pytest -v특정 테스트 실행:
.\.venv\Scripts\python -m pytest tests/test_catalog.py::test_catalog_contains_expected_services -v수동 스모크 테스트 (HTTP)
PowerShell:
$headers = @{ Accept = "application/json" }
Invoke-WebRequest -Uri "http://127.0.0.1:8000/health" -Headers $headers -Method GET
Invoke-WebRequest -Uri "http://127.0.0.1:8000/docs/services" -Headers $headers -Method GET
Invoke-WebRequest -Uri "http://127.0.0.1:8000/docs/resource?uri=pharus://services/rif" -Headers $headers -Method GETbash/curl:
curl -s http://127.0.0.1:8000/health | jq .
curl -s http://127.0.0.1:8000/docs/services | jq .
curl -s 'http://127.0.0.1:8000/docs/resource?uri=pharus://services/rif' | jq .프로젝트 의존성
pyproject.toml에 나열된 주요 의존성:
fastapi - 비동기 웹 프레임워크
httpx - 비동기 HTTP 클라이언트
pydantic - 데이터 유효성 검사
mcp - Model Context Protocol
sqlalchemy - ORM (해당되는 경우)
pytest - 테스트 프레임워크
python-dotenv - .env 지원
기여
기여를 환영합니다! 다음 절차를 따라주세요:
저장소를 포크(Fork)합니다.
기능 브랜치를 생성합니다 (
git checkout -b feature/new-feature)변경 사항을 커밋합니다 (
git commit -am '새로운 기능 추가')브랜치에 푸시합니다 (
git push origin feature/new-feature)Pull Request를 생성합니다.
코드 표준
타입 힌트가 포함된 Python 3.12+ 사용
PEP 8 표준 준수 (
black또는autopep8도구로 포맷팅)함수와 클래스는 포르투갈어 docstring으로 문서화
새로운 기능에 대한 단위 테스트 작성
문제 해결
오류: "not a git repository"
git init으로 저장소를 초기화하세요.
오류: 업스트림 서비스 호출 시 "Connection refused"
.env의 URL이 올바른지, 서비스가 예상 포트에서 실행 중인지 확인하세요.
오류: "Port already in use"
.env에서 포트를 변경하거나 명령줄에서 --port를 사용하세요.
테스트 실패
업스트림 서비스가 실행 중인지 확인하세요. 진단을 위해 --check-only를 사용하세요:
.\.venv\Scripts\python .\scripts\start_services.py --check-only라이선스
이 프로젝트는 MIT 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 참조하세요.
저자 및 관리자
MPMG 기술 팀 개발
질문, 제안 또는 버그 보고는 GitHub 저장소에 이슈를 생성해주세요.
최종 업데이트: 2026년 4월 버전: 1.0.0 상태: 활성
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
MCP server for Brazilian Federal Senate open data (legislative, administrative, e-Cidadania).
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
An MCP server for deep research or task groups
Appeared in Searches
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/rfalexandre/pharus-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server