api-server-mcp
REST API server and MCP protocol integration
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- api-server-mcp
- priority
- critical
- description
- REST API server and MCP protocol integration
03 SKILL.md 正文
API Server & MCP Protocol
Axum server design for document extraction endpoints, middleware, async processing, and Model Context Protocol integration for AI agents
Copied from upstream
xbergand now known-stale in one place (same class of gap the Unreleased changelog already flagged forcrate-structure/alef-generated-bindings): the "MCP Tools" section below lists three tools (extract,extract_batch,get_capabilities). Reading the pinned xberg commit's actual source (crates/xberg/src/mcp/server.rs) shows eight:extract,extract_batch,detect_mime_type,cache_stats,cache_clear,cache_manifest,cache_warm,get_version. This also does not describe hacienda's own MCP server —hacienda-mcp(hacienda mcp serve), which wrapsHaciendaFacade, not xberg's API — see that crate's module doc andsuperpowers/specs/2026-08-13-M1-mcp-server-and-cli-sdk-parity-design.md.
Xberg API Architecture
Location: crates/xberg/src/api/, crates/xberg-cli/
Xberg provides a dual REST API + MCP server built with Axum + Tokio.
Request Flow:
HTTP Client / AI Agent (Claude)
|
[Transport Layer]
├── REST API (Axum HTTP)
└── MCP Protocol (HTTP or Stdio)
|
[Middleware Layer]
├── CORS, Request Logging (TraceLayer)
├── Request/Response size limits
└── Rate limiting (optional)
|
[Router]
├── REST Endpoints
│ ├── POST /extract - File upload extraction
│ ├── POST /extract-url - URL-based extraction
│ ├── GET /formats - List supported formats
│ ├── GET /health - Server health check
│ ├── POST /batch - Batch document processing
│ ├── GET /cache/stats - Cache statistics
│ └── DELETE /cache - Clear extraction cache
├── MCP Endpoints
│ ├── POST /mcp/tools - List available tools
│ ├── POST /mcp/tools/call - Call a tool
│ ├── GET /mcp/resources - List resources
│ ├── GET /mcp/resources/:uri - Read resource
│ ├── GET /mcp/prompts - List prompts
│ └── GET /mcp/prompts/:name - Get prompt
|
[Handler / Tool Layer]
├── extract_handler / extract tool
├── extract_async_handler / extract_batch tool
├── health_handler / get_capabilities tool
└── format_handler
|
[Extraction Core]
├── Format detection
├── Extraction pipeline
├── Post-processing (chunking, embeddings)
└── Result formatting
|
JSON Response / MCP ToolResult
Server Setup & Configuration
Location: crates/xberg/src/api/server.rs
Server initialization pattern: Create ApiState (holds ExtractionConfig + ExtractionCache), build Axum Router with all REST + MCP routes, apply middleware layers (body limits, CORS, tracing), serve via tokio::net::TcpListener.
Key middleware layers applied in order:
DefaultBodyLimit::max(100MB)+RequestBodyLimitLayer-- configurable via env varsCorsLayer::permissive()-- restrict in production viaCORS_ALLOWED_ORIGINSTraceLayer::new_for_http()-- request/response logging
Core REST Handlers
Location: crates/xberg/src/api/handlers.rs
| Handler | Method | Description |
|---|---|---|
extract_handler |
POST /extract | Multipart files, URL fields, or JSON inputs; build ExtractInput and call extract() / extract_batch() |
extract_async_handler |
POST /extract-async | Queue the same unified extraction input shape for async processing |
health_handler |
GET /health | Report status, version, uptime, feature availability (OCR, embeddings), cache stats |
formats_handler |
GET /formats | Return supported format categories (office, pdf, images, web, email, archives, academic) |
cache_stats_handler |
GET /cache/stats | Hit/miss counts and hit rate |
cache_clear_handler |
DELETE /cache | Clear LRU cache |
Caching Strategy
Location: crates/xberg/src/cache/mod.rs
LRU cache keyed by SHA256(file_content), stores Arc<ExtractionResult>. Default 1000 entries. Thread-safe via RwLock. Tracks hit/miss counters with AtomicU64 for stats endpoint.
Error Handling
Location: crates/xberg/src/api/error.rs
ApiError enum maps to HTTP status codes:
MissingFile-> 400,FileNotFound-> 404OnnxRuntimeMissing/TesseractMissing-> 503 (with remediation message)PayloadTooLarge-> 413ExtractionFailed/InvalidConfig/UnsupportedFormat-> 500
MCP Server Implementation
Location: crates/xberg/src/mcp/server.rs
The MCP server allows Claude and other AI agents to call Xberg extraction functions through the Model Context Protocol.
MCP Tools (Callable Functions)
Three tools are registered:
| Tool | Purpose | Required Params |
|---|---|---|
extract |
Extract text/tables/metadata from bytes, paths, file URIs, or URLs | input |
extract_batch |
Extract from multiple unified inputs in parallel | inputs[] |
get_capabilities |
List supported formats, features, backends | (none) |
Tool registration pattern (example: extract):
// Define Tool with name, description, JSON Schema inputSchema
// Register with server.register_tool(tool, handler_fn)
// Handler: parse params -> build ExtractInput + ExtractionConfig -> call extract() -> return ToolResult as JSON
extract optional params: mime_type, filename, extract_tables, extract_images, ocr_enabled, extract_metadata, chunking_preset, generate_embeddings, and URL ingestion options.
MCP Resources (Static Knowledge)
Three resources provide static information to agents:
xberg://formats-- Supported format list as JSONxberg://features-- Cross-binding feature matrix (fromFEATURE_MATRIX.md)xberg://api-reference-- Generated API documentation
MCP Prompts (Agent Templates)
Two prompts guide agent extraction workflows:
extract_for_rag-- Document type-specific RAG extraction guidance (research paper, contract, report). Recommends chunking preset and embedding config.batch_document_processing-- Optimal concurrency, grouping, and error handling for batch workflows.
MCP Transport Protocols
- HTTP/REST: MCP routes mounted alongside REST API on separate
/mcp/prefix - Stdio: JSON-RPC 2.0 over stdin/stdout for local CLI integration (e.g., Claude Desktop)
Integration with Claude Desktop
{
"mcpServers": {
"xberg": {
"command": "xberg-mcp",
"env": {
"XBERG_API_BASE": "http://localhost:8000",
"XBERG_MCP_TRANSPORT": "stdio"
}
}
}
}
MCP Error Handling
ToolError variants: FileNotFound, UnsupportedFormat, ExtractionFailed, OnnxRuntimeMissing, TesseractMissing, Timeout. Each maps to an MCP ToolResultError with descriptive code and message.
Environment Configuration
See .env.example for all configurable variables. Key categories:
- Server:
XBERG_HOST,XBERG_PORT - Size limits:
XBERG_MAX_REQUEST_BODY_BYTES(default 100MB),XBERG_MAX_MULTIPART_FIELD_BYTES - Features:
XBERG_ENABLE_OCR,XBERG_ENABLE_EMBEDDINGS,XBERG_ENABLE_KEYWORDS - Cache:
XBERG_CACHE_ENABLED,XBERG_CACHE_SIZE - CORS:
CORS_ALLOWED_ORIGINS(comma-separated) - MCP:
XBERG_MCP_HOST,XBERG_MCP_PORT,XBERG_MCP_TRANSPORT(stdio/http) - Logging:
RUST_LOG=xberg=info,tower_http=debug
Critical Rules
REST API Rules
- Always validate multipart file uploads - Check MIME type, size, magic bytes
- Timeout long-running extractions - Set per-handler timeout (5 min default)
- Stream large files - Never buffer entire multi-GB file in memory
- Cache aggressively - Identical files should return from cache in <1ms
- Parallel extraction is CPU-bound - Limit workers to CPU count + 1
- Error responses must be actionable - Include error code and remediation suggestion
- Health checks must verify features - Report missing dependencies (ONNX, Tesseract)
- Size limits are configurable - Allow override via env var for large deployments
- CORS is permissive by default - Restrict in production via env var
- Logging all requests - Track extraction metrics for observability
MCP Rules
- All tools must have timeout - Prevent hanging on large files (default 5 min)
- Error responses must be detailed - Include suggestions for missing dependencies
- Feature gates must be checked - Return helpful message if feature unavailable (embeddings, OCR)
- Resources should be static - Don't query external services in resource handlers
- Prompts guide agents - Provide clear examples and best practices
- Batch tools must support cancellation - Allow agent to stop long-running batch operations
- Logging all tool calls - Track usage for analytics and debugging
Related Skills
- extraction-pipeline-patterns - Core extraction called by handlers and MCP tools
- chunking-embeddings - Optional chunking/embedding parameters in extraction
- ocr-backend-management - OCR engine selection and image preprocessing
04 同仓库更多 Skills
impeccable
Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
wasm-constraints
WASM build constraints for the crates/xberg-wasm crate — the wasm-target feature set, no-tokio sync-only internal APIs, the mandatory SyncExtractor trait for WASM-compatible extractors, the 2 MB HTML size limit, size-optimized build config (opt-level="z"), and the async-wrapper/sync-internal API pattern. Load when building for wasm32, adding or modifying a WASM-compatible extractor, or debugging WASM build/runtime failures.
release-versioning
How xberg versions are synced and released — Cargo.toml is the single source of truth, `task version:sync` propagates it to alef-managed binding manifests AND the integrations under integrations/, which are versioned and published in lockstep with core (including -rc.N). Load before bumping a version, editing the version-sync task, or touching an integration's version/xberg dependency.
plugin-architecture-patterns
Plugin architecture, registration, and trait patterns
mime-detection-routing
MIME type detection and extractor routing in core/mime.rs and core/extractor/bytes.rs — the extension→EXT_TO_MIME→validate→registry→extractor flow, key detection functions, the 118+ case-insensitive extension map, priority-based registry selection, wildcard MIME families, and how to add a new MIME type. Load when adding a format, wiring an extractor to a MIME type, or debugging why a file routes to the wrong (or no) extractor.
format-specific-extraction
Format-specific document extraction workflows