Readium Mcp Server - Git To Markdown

Readium MCP

一个 Model Context Protocol (MCP) 服务，可为 Claude 等大模型和其他兼容 MCP 的客户端提供 Readium 强大的文档分析功能。

🔍 这是什么？

Readium MCP 是大模型与任意文档仓库之间的桥梁，可用于：

• 分析本地目录、公开或私有 Git 仓库以及 URL
• 处理多种文件格式（代码、Markdown、文本）
• 将网页转换为 Markdown 以供分析
• 提供包含摘要、文件树和内容的结构化结果

适用于需要大模型分析大量文档、代码仓库或技术网站的场景。

🚀 安装

使用 pip（推荐）

pip install readium-mcp

从源代码安装

# Clone the repository
git clone https://github.com/tu-usuario/readium-mcp.git
cd readium-mcp

# Install dependencies with Poetry
poetry install

🛠️ 使用方法

直接运行

readium-mcp

使用 Poetry（从源代码安装）

poetry run readium-mcp

🔌 与 MCP 客户端集成

VSCode

将以下内容添加到 VSCode 配置（settings.json）中：

{
  "mcp": {
    "servers": {
      "readium": {
        "command": "readium-mcp"
      }
    }
  }
}

或者在项目中创建 .vscode/mcp.json 文件：

{
  "servers": {
    "readium": {
      "command": "readium-mcp"
    }
  }
}

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "readium": {
      "command": "readium-mcp"
    }
  }
}

MCP CLI

# Install
mcp install -n readium -- readium-mcp

# Inspect
mcp inspect readium

# Test in console
mcp call-tool readium analyze_docs --path https://github.com/modelcontextprotocol/servers.git

📝 提供的工具

analyze_docs

使用 Readium 分析本地目录、Git 仓库或 URL 中的文档。

参数

参数	类型	说明	默认值
path	string	本地路径、GitHub URL 或文档 URL	（必填）
branch	string	如果是仓库，则使用的分支	null
target_dir	string	要分析的特定子目录	null
use_markitdown	boolean	使用 Markitdown 进行转换	false
url_mode	string	URL 处理模式（'clean'、'full'）	"clean"
max_file_size	integer	文件大小上限，单位为字节	5242880（5MB）
exclude_dirs	array	要排除的目录	[]
exclude_ext	array	要排除的扩展名（例如 ['.png']）	[]
include_ext	array	要包含的扩展名（例如 ['.md']）	[]

响应

{
  "content": [
    {"type": "text", "text": "Summary:\n..."},
    {"type": "text", "text": "Tree:\n..."},
    {"type": "text", "text": "Content:\n..."}
  ],
  "isError": false
}

🧪 测试

单元测试

poetry run pytest

直接测试 Readium

python test.py

🧩 Python 使用示例

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_readium_mcp():
    server_params = StdioServerParameters(
        command="readium-mcp"
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List tools
            tools = await session.list_tools()
            print(f"Available tools: {tools}")

            # Analyze a repository
            result = await session.call_tool(
                "analyze_docs",
                {"path": "https://github.com/modelcontextprotocol/servers.git"}
            )

            print(f"Analysis result: {result}")

# Run
asyncio.run(test_readium_mcp())

📋 优势

• 快速：即使处理大型仓库，也能高效分析
• 灵活：支持本地目录、Git 仓库和 URL
• 可配置：可自定义要分析的扩展名、大小和目录
• 兼容性强：适用于任何 MCP 客户端（Claude、VSCode、CLI）
• 简单：没有复杂依赖，使用 stdio 传输以实现最大兼容性

🤝 参与贡献

欢迎贡献。请随时：

1. Fork 此仓库
2. 为你的功能创建分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

👏 致谢

• 感谢 Readium 提供强大的文档分析功能
• 感谢 Model Context Protocol 提供标准的大模型通信协议
• 感谢 FastMCP 提供用于 MCP 的 Python SDK

---

由 Pablo Toledo 用 ❤️ 开发