Gutemberg Extractor MCP

Gutenberg Extractor MCP服务器-完整文档

描述

MCP（模型上下文协议）服务器，用于从Gutenberg文件中提取嵌入式资源。完全符合MCP协议2024-11-05。

特性

MCP协议合规性

• ✅ 初始化：完全支持MCP协议初始化请求
• ✅ 工具/列表：实现工具/list方法以返回可用工具的列表
• ✅ JSON-RPC 2.0：正确处理MCP协议JSON-RPC 2.0请求
• ✅ 工具注册：工具在响应中正确注册
• ✅ 检测：MCP系统正确检测到服务器
• ✅ 测试：完整的协议合规性测试套件

功能

1. 提取资源：从Gutenberg文件中提取嵌入式资源（SVG、PNG、JPG、WebP、GIF）
2. 分析文件：分析文件以检测嵌入式资源，而无需处理
3. 分批处理：批量处理多个Gutenberg文件
4. get_统计：获取详细的优化统计数据
5. list_supportd_types：列出支持的资源类型

安装与配置

需求

• Python 3.9+
• 库：asyncio、json、日志、pathlib

MCP配置

1. MCP设置中的配置:

{
  "mcpServers": {
    "gutenberg-extractor": {
      "command": "python",
      "args": ["mcp_server.py", "--stdio"],
      "cwd": "/path/to/tools/gutenberg-extractor"
    }
  }
}

服务器使用情况

标准模式（生产）

python mcp_server.py --stdio

HTTP模式（开发）

python mcp_server.py --host localhost --port 8080

MCP协议API

初始化

请求:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "client-name",
      "version": "1.0.0"
    }
  }
}

响应:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "gutenberg-extractor",
      "version": "2.0.0",
      "description": "MCP server for extracting embedded resources from Gutenberg files"
    }
  }
}

工具/列表

请求:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

响应:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "extract_resources",
        "description": "Extract embedded resources from a Gutenberg file (SVG, PNG, JPG, etc.)",
        "inputSchema": {
          "type": "object",
          "properties": {
            "file_path": {
              "type": "string",
              "description": "Path of the Gutenberg file to process"
            },
            "threshold_kb": {
              "type": "integer",
              "description": "Threshold in KB to extract resources",
              "default": 1
            },
            "output_dir": {
              "type": "string",
              "description": "Optional output directory"
            }
          },
          "required": ["file_path"]
        }
      }
      // ... more tools
    ]
  }
}

工具/调用-提取资源

请求:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "extract_resources",
    "arguments": {
      "file_path": "/path/to/gutenberg.template",
      "threshold_kb": 1,
      "output_dir": "/path/to/output"
    }
  }
}

响应:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "success": true,
    "error": null,
    "results": {
      "original_file": "/path/to/gutenberg.template",
      "optimized_file": "/path/to/gutenberg_optimized.template",
      "assets_directory": "/path/to/output/assets",
      "extracted_resources_count": 15,
      "statistics": {
        "original_size": 1024000,
        "optimized_size": 875200,
        "extracted": 15,
        "bytes_saved": 148800
      },
      "reduction_percentage": 14.53,
      "metadata_file": "/path/to/extraction_metadata.json"
    }
  }
}

传统兼容性

服务器保持与传统方法的兼容性，以方便迁移：

• extract_resources （直接通话）
• analyze_file （直接通话）
• batch_process （直接通话）
• get_statistics （直接通话）
• list_supported_types （直接通话）

测试与验证

运行合规性测试

python test_mcp_compliance.py

包含的测试

1. 初始化测试：验证正确的初始化响应
2. 工具/列表测试：验证完整的工具列表
3. 工具/通话测试：测试工具执行
4. 传统方法测试：确认传统兼容性
5. 错误处理测试：验证JSON-RPC错误处理

测试报告

===========================================================
FINAL TEST REPORT
===========================================================
initialize: ✅ PASSED
tools_list: ✅ PASSED  
tools_call: ✅ PASSED
legacy_methods: ✅ PASSED
error_handling: ✅ PASSED

Total: 5/5 tests passed
🎉 All tests passed! The server complies with the MCP protocol

完整使用示例

import asyncio
import json

# Simulate initialize request
initialize_request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize", 
    "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
}

# Simulate tools/list request
tools_list_request = {
    "jsonrpc": "2.0", 
    "id": 2,
    "method": "tools/list",
    "params": {}
}

# Simulate tools/call request for list_supported_types
tools_call_request = {
    "jsonrpc": "2.0",
    "id": 3, 
    "method": "tools/call",
    "params": {
        "name": "list_supported_types",
        "arguments": {}
    }
}

故障排除

未检测到服务器

1. 验证设置中的MCP配置
2. 运行合规性测试： python test_mcp_compliance.py
3. 检查服务器日志是否有错误
4. 确认 mcp_server.py 文件是可执行的

工具未出现

1. 验证初始化是否正确运行
2. 确认工具/列表响应工具列表
3. 检查工具/列出响应结构

JSON-RPC错误

1. 验证请求的JSON格式
2. 验证正确的错误代码（-32601、-32602、-32603）
3. 确认协议版本匹配

日志记录和调试

服务器使用配置如下的日志记录：

logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

重要日志

• INFO - Starting MCP server in stdio mode
• INFO - Sending request: {method}
• INFO - Response received: {server_name}
• ERROR - Error handling request: {error}

项目结构

tools/gutenberg-extractor/
├── mcp_server.py              # Main MCP server
├── test_mcp_compliance.py     # Test suite
├── gutenberg_extractor.py     # Base extractor
├── README.md                  # This documentation
├── example_usage.sh          # Usage example
└── setup_mcp.sh             # Configuration script

版本和更新

• v2.0.0版本：完全符合MCP协议
• v1.0.0：基本初始版本

v2.0.0中的更改

• ✅ 完成初始化/初始化实现
• ✅ 支持工具/列表和工具/调用
• ✅ 正式MCP工具注册
• ✅ 正确的JSON-RPC 2.0响应结构
• ✅ 合规性测试套件
• ✅ 与传统方法的兼容性

贡献

1. 运行测试： python test_mcp_compliance.py
2. 提交前验证MCP合规性
3. 用适当的模式记录新工具
4. 保持与遗留方法的向后兼容性