Sakutto Works 데이터 정규화 인프라를 위한 공식 Model Context Protocol (MCP) 서버입니다.
이 저장소는 **Project GHOST SHIP (Agent-Commerce-OS)**을 위한 공식 MCP 서버를 제공합니다. 이 서버는 AI 에이전트(예: Claude Desktop)가 Polar.sh를 통해 관리되는 제로 트러스트(Zero-Trust) 계량형 API에 자율적으로 연결할 수 있도록 지원합니다. 이 통합을 통해 에이전트는 비정형 웹 데이터를 추출하여 깔끔하고 토큰 최적화된 Markdown 또는 JSON 형식으로 정규화할 수 있습니다.
Related MCP server: deltav-edge-mcp-server
🛡️ 제로 트러스트 엣지 보안: Cloudflare Edge에서의 엄격한 프롬프트 인젝션 차단 및 경계 방어.
🧩 MCP 네이티브: Claude Desktop과 같은 Model Context Protocol 클라이언트와 즉각적이고 원활한 통합.
⚡ Lite GraphQL 필터링: 선택적 fields 배열을 전달하여 에이전트가 필요한 정확한 데이터 노드만 추출함으로써 컨텍스트 윈도우 토큰 소비를 획기적으로 최소화합니다.
💳 순수 종량제: Polar.sh 기반으로 성공적인 호출당 $0.10가 부과됩니다. 숨겨진 수수료나 강제 구독이 없습니다.
🤖 자율 오류 복구: MCP 표준 오류 형식(isError: true)을 엄격히 준수합니다. 엣지 게이트웨이로부터 402 Payment Required 및 429 Too Many Requests를 지능적으로 전달하여, AI 에이전트가 개발자의 개입 없이도 예산 부족을 해결하거나 무한 루프를 중단하도록 인간 사용자에게 자율적으로 안내할 수 있습니다.
🔍 분산 추적 및 관측성: 모든 요청에는 전체 인프라(게이트웨이 -> 엔진 -> R2 감사 로그)를 통해 전파되는 고유한 trace_id가 할당됩니다. 오류 발생 시 이 Trace ID가 에이전트의 텍스트 응답에 직접 삽입되어, 수동 로그 검색 없이도 즉각적이고 정밀한 디버깅 및 엔터프라이즈급 지원이 가능합니다.
🔄 고급 라우팅 (동기/비동기 및 티어링): AI 에이전트는 추출 파이프라인을 동적으로 지시할 수 있습니다. target_tier(예: Actionable Data, Compliance Check)를 제공하여 엔진의 스키마를 조정합니다. 또한 webhook URL을 전달하여 무거운 추출 작업을 백그라운드에서 처리(즉시 202 Accepted 및 작업 ID 수신)함으로써 MCP 시간 제한을 방지할 수 있습니다. 웹훅이 제공되지 않으면 시스템은 동기식 실행으로 원활하게 전환됩니다.
당사의 인프라는 3계층 제로 트러스트 모델에서 운영됩니다. 전체적인 구조는 관련 저장소에서 확인할 수 있습니다:
Layer C (본 저장소): 로컬 AI 에이전트와 원격 네트워크를 연결하는 상태 비저장 MCP 서버.
Layer A (agent-commerce-gateway): 제로 트러스트 인증, 라우팅 및 계량형 청구를 처리하는 Cloudflare Workers.
Layer B (agent-commerce-core): 고급 RAG 최적화 의미론적 데이터 정규화를 수행하는 Google Cloud Run 엔진.
Node.js (v18 이상 권장) 및 npm 설치.
활성화된 Polar.sh API 키 (요청당 $0.10 계량 청구). 공식 API 키 결제 페이지에서 획득하십시오.
Claude Desktop 또는 표준 MCP 호환 클라이언트.
AI 에이전트에 정규화 도구에 대한 액세스 권한을 부여하려면 claude_desktop_config.json에 다음 구성을 추가하십시오:
~/Library/Application Support/Claude/claude_desktop_config.json
%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/v1/normalize_web_data"
}
}
}
}(참고: /absolute/path/to/ghost-ship-mcp-server는 복제된 저장소의 실제 절대 경로로, your_polar_api_key_here는 활성화된 Polar.sh API 키로 바꾸십시오.)
이 저장소를 파싱하여 도구를 통합하려는 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 쿼리 매개변수로 자동 추가합니다.
동적 추출 티어 (target_tier): AI 에이전트는 대상 스키마 티어(a1, a2 등)를 지정하여 추출 로직을 즉석에서 변경할 수 있습니다(예: 표준 마크다운 대 엄격한 실행 가능 가용성 데이터 추출).
비동기 웹훅 (webhook): 장시간 실행되는 추출 작업의 경우, 에이전트는 대상 URL이 포함된 webhook 객체를 제공할 수 있습니다. 서버는 즉시 job_id를 반환하여 에이전트가 대기하지 않고 작업을 계속할 수 있도록 합니다. 결함 허용 설계: 에이전트가 웹훅 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 buildMCP 서버를 시작합니다:
npm start오픈 소스 커뮤니티의 기여를 환영하고 장려합니다! Pull Request를 제출할 때는 다음 사항을 확인하십시오:
코드가 성공적으로 빌드되어야 합니다 (npm run build).
모든 테스트가 로컬에서 통과해야 합니다 (npx vitest 또는 선호하는 테스트 러너 사용).
기존 코드 스타일과 표준 TypeScript 관행을 준수해야 합니다.
이 프로젝트는 표준 오픈 소스 행동 강령을 따릅니다. 참여함으로써 존중하고 협력적인 의사소통을 유지할 것으로 기대됩니다.
공식 포털 및 에이전트 문서: Sakutto Works
GitHub 조직: SakuttoWorks
개발자 프로필: SakuttoWorks 프로필
버그 보고 및 기능 요청: 버그를 보고하거나 새로운 추출 기능을 제안하려면 GitHub Issues 페이지를 사용하십시오.
이 프로젝트는 ISC 라이선스에 따라 라이선스가 부여됩니다. 책임 및 자율 에이전트 사용에 대한 자세한 내용은 LEGAL.md를 읽어보십시오.
Agent-Commerce-OS가 엔지니어링 시간을 절약해주었거나 AI 워크플로우를 확장하는 데 도움이 되었다면, 후원자가 되거나 일회성 팁을 고려해주십시오. 귀하의 기여는 서버 비용을 직접 충당하고, 엣지 게이트웨이의 고가용성을 보장하며, 지속적인 오픈 소스 개발을 촉진합니다.
© 2026 Sakutto Works. 에이전트 경제를 위한 시맨틱 웹 표준화.
Extracts, sanitizes, and normalizes unstructured web content into clean Markdown or JSON. Highly optimized for LLM context windows. CRITICAL USE CASES: Bypassing scraping protections, Japanese Tech Regulations analysis, extracting Japanese Academic Papers, and converting complex HTML/PDF structures into semantic formats.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The target URL to extract and normalize. | |
| format_type | No | Desired output format. Supported values: 'json', 'markdown'. | |
| fields | No | Schema Filtering (Lite GraphQL): Array of fields to extract, minimizing token consumption. | |
| target_tier | No | Extraction schema tier (e.g., 'a1' for async processing, 'a2' for actionable data, 'a3' for compliance). Defaults to standard. | |
| webhook | No | Webhook configuration for asynchronous processing. Required if target_tier is 'a1'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It notes it's 'optimized for LLM context windows' and mentions 'bypassing scraping protections', which implies potential risk. But does not disclose auth needs, rate limits, or side effects beyond the listed use cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with core function and lists use cases in a structured way. Slightly verbose with capitalized 'CRITICAL USE CASES', but overall efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains output formats (Markdown/JSON) and use cases. It lacks error handling, size limits, or rate limit info, but for a web extraction tool, it provides sufficient context for an AI agent to decide usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds little beyond the schema, only emphasizing output format and use cases. Baseline 3 is appropriate as the schema already provides sufficient meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it extracts, sanitizes, and normalizes web content into Markdown/JSON, with specific use cases listed. Verb+resource+output are explicit, and no sibling tools exist to confuse.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides critical use cases (bypassing scraping protections, Japanese content, complex conversions), giving context on when to use. However, no explicit when-not-to-use or alternatives are mentioned, but since no siblings, it's adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
normalize_web_data5 fields changedInput schema / properties / fields / descriptionPrevious value: -"Schema Filtering (Lite GraphQL): Comma-separated list of fields to extract, minimizing token consumption (e.g., 'title,content')."New value: +"Schema Filtering (Lite GraphQL): Array of fields to extract, minimizing token consumption."Input schema / properties / fields / itemsAdded value: +{
+ "type": "string"
+}Input schema / properties / fields / typePrevious value: -"string"New value: +"array"Input schema / properties / target_tierAdded value: +{
+ "description": "Extraction schema tier (e.g., 'a1' for async processing, 'a2' for actionable data, 'a3' for compliance). Defaults to standard.",
+ "type": "string"
+}Input schema / properties / webhookAdded value: +{
+ "additionalProperties": false,
+ "description": "Webhook configuration for asynchronous processing. Required if target_tier is 'a1'.",
+ "properties": {
+ "url": {
+ "description": "The webhook endpoint URL to receive async results.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+}v1.0.0normalize_web_dataScored across 1 tool
With only one tool, there is no possibility of confusion between tools. The single tool has a clear, comprehensive purpose.
A single tool name presents no inconsistency issues. The naming is clear and descriptive of its function.
One tool for a broad scope that includes multiple specialized use cases (bypassing scraping protections, extracting academic papers, etc.) feels insufficient. The tool is expected to handle a wide range of operations, likely warranting a few more focused tools.
The tool covers the core extraction, sanitization, and normalization workflow. Minor gaps could exist around configuration options or error handling, but the main domain is addressed.
Cross-OEM industrial machine intelligence: identity, normalization, automation, attestation.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Edge content delivery for autonomous agents — signed manifests, A2A authentication
Blockchain SSN for AI agents. MCP gateway that blocks at the point of action, tamper evident audit.
