Agent-Commerce-OS MCP 서버

Sakutto Works 데이터 정규화 인프라를 위한 공식 MCP(Model Context Protocol) 서버입니다.

🚀 개요

이 저장소는 **Project GHOST SHIP (Agent-Commerce-OS)**를 위한 공식 MCP 서버를 제공합니다. 이 서버를 통해 AI 에이전트(예: Claude Desktop)는 Polar.sh를 통해 관리되는 제로 트러스트 기반의 종량제 API에 자율적으로 연결할 수 있습니다. 이 통합을 통해 에이전트는 비정형 웹 데이터를 추출하여 토큰 최적화된 깔끔한 Markdown 또는 JSON 형식으로 정규화할 수 있습니다.

🏗️ 아키텍처

당사의 인프라는 3계층 제로 트러스트 모델에서 운영됩니다. 전체적인 구조를 이해하려면 관련 저장소를 살펴보시기 바랍니다:

Layer C (본 저장소): 로컬 AI 에이전트와 원격 네트워크를 연결하는 상태 비저장(stateless) MCP 서버.
Layer A (agent-commerce-gateway): 제로 트러스트 인증, 라우팅 및 종량제 과금을 처리하는 Cloudflare Workers.
Layer B (agent-commerce-core): 고급 RAG 최적화 의미론적 데이터 정규화를 수행하는 Google Cloud Run 엔진.

⚙️ 사전 요구 사항

활성화된 Polar.sh API 키 (요청당 $0.10 종량제 과금). 공식 API 키 결제 페이지에서 획득하세요.
Claude Desktop 또는 MCP 호환 클라이언트.

🔌 설정 및 구성 (Claude Desktop)

AI 에이전트에 정규화 도구에 대한 액세스 권한을 부여하려면 claude_desktop_config.json에 다음 구성을 추가하세요:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent-commerce-os": {
      "command": "node",
      "args": [
        "/absolute/path/to/ghost-ship-mcp-server/dist/index.js"
      ],
      "env": {
        "POLAR_API_KEY": "your_polar_api_key_here",
        "GATEWAY_URL": "https://api.sakutto.works"
      }
    }
  }
}

(참고: /absolute/path/to/ghost-ship-mcp-server는 복제한 저장소의 실제 절대 경로로, your_polar_api_key_here는 활성화된 Polar.sh API 키로 바꾸십시오.)

🧠 자율 AI 에이전트를 위한 안내

이 저장소를 파싱하여 도구를 통합하려는 AI 에이전트나 LLM인 경우:

전체 의미론적 컨텍스트와 기능은 llms.txt를 읽어주세요.
정확한 도구 스키마는 mcp.json에 정의되어 있습니다.
URL을 추측하거나 합성하지 마십시오. 항상 공식 Sakutto Works 포털을 참조하십시오.

🤖 사용 가능한 도구

StdioServerTransport를 통해 연결되면, AI 에이전트는 @modelcontextprotocol/sdk를 사용하여 McpServer 인스턴스에 의해 동적으로 노출되는 도구를 자동으로 검색합니다. (이러한 기능은 외부 레지스트리를 위해 mcp.json 매니페스트에도 카탈로그화되어 있습니다):

normalize_web_data: 비정형 웹 콘텐츠를 추출하여 LLM 컨텍스트 윈도우에 최적화된 깔끔한 의미론적 Markdown 또는 JSON 형식으로 정규화합니다.
- 스키마 필터링 (fields): 선택적 fields 매개변수를 통해 Lite GraphQL 스타일의 필드 선택을 지원합니다. 이를 통해 AI 에이전트는 특정 데이터 노드만 요청하여 토큰 소비와 응답 지연 시간을 크게 최소화할 수 있습니다. 지정된 경우, 서버는 게이트웨이로 요청을 라우팅하기 전에 이러한 필드를 URL 쿼리 매개변수로 자동으로 추가합니다.
- 엄격한 유효성 검사: 모든 도구 입력은 zod를 사용하여 엄격하게 정의 및 검증되므로 Layer B의 기본 사양을 강력하게 준수합니다. 검증이 완료되면 서버는 POLAR_API_KEY를 사용하여 인증된 HTTP POST를 통해 게이트웨이로 요청을 안전하게 전달합니다.

💻 로컬 개발 및 설정

서버를 로컬에서 실행하거나 개발 환경을 준비하려면:

저장소를 복제하고 디렉토리로 이동합니다:

git clone https://github.com/SakuttoWorks/ghost-ship-mcp-server.git
cd ghost-ship-mcp-server

필요한 종속성(@modelcontextprotocol/sdk 및 zod 포함)을 설치합니다:
```
npm install
```
환경 변수를 구성합니다:
```
cp .env.example .env
```
(새로 생성된 .env 파일을 열고 POLAR_API_KEY를 삽입한 다음, GATEWAY_URL이 https://api.sakutto.works 또는 https://api.sakutto.works/v1/normalize_web_data와 같은 특정 엔드포인트 경로로 설정되어 있는지 확인하십시오.)
TypeScript 소스 코드를 컴파일합니다:
```
npm run build
```
MCP 서버를 시작합니다:
```
npm start
```

🤝 기여

오픈 소스 커뮤니티의 기여를 환영하고 장려합니다! Pull Request를 제출할 때는 다음 사항을 확인하십시오:

코드가 성공적으로 빌드되는지 (npm run build).
모든 테스트가 로컬에서 통과하는지 (npx vitest 또는 선호하는 테스트 러너 사용).
기존 코드 스타일과 표준 TypeScript 관행을 준수하는지.

🌍 리소스 및 이슈 추적

공식 포털 및 에이전트 문서: Sakutto Works
GitHub 조직: SakuttoWorks
개발자 프로필: SakuttoWorks 프로필
버그 리포트 및 기능 요청: 버그를 보고하거나 새로운 추출 기능을 제안하려면 GitHub Issues 페이지를 사용하십시오.

📄 라이선스

이 프로젝트는 ISC 라이선스에 따라 라이선스가 부여됩니다. 책임 및 자율 에이전트 사용에 관한 자세한 내용은 LEGAL.md를 읽어보십시오.

💖 프로젝트 후원

Agent-Commerce-OS가 엔지니어링 시간을 절약해주었거나 AI 워크플로우를 확장하는 데 도움이 되었다면, 스폰서가 되거나 일회성 팁을 고려해 주십시오. 귀하의 기여는 서버 비용을 직접 충당하고, 엣지 게이트웨이의 고가용성을 보장하며, 지속적인 오픈 소스 개발의 원동력이 됩니다.

SakuttoWorks-Data-Normalizer