Unstructured API MCP 服务器

一个用于与 Unstructured API 交互的 MCP 服务器实现。此服务器提供了列出源和工作流的工具。

设置

1. 安装依赖项：

• uv add "mcp[cli]"
• uv pip install --upgrade unstructured-client python-dotenv

或者使用 uv sync。

1. 将您的 Unstructured API 密钥设置为环境变量。
   • 在根目录下创建一个 .env 文件，并添加包含您的密钥的一行：UNSTRUCTURED_API_KEY="YOUR_KEY"

在本地测试时，任何指向生产环境的有效密钥都可以工作。然而，为了能够从客户端（例如 Claude for Desktop）返回有效结果，您需要从 https://platform.unstructured.io/app/account/api-keys 获取的个人密钥。

运行服务器

使用 MCP CLI：

mcp run uns_mcp/server.py

或：

uv run uns_mcp/server.py

可用工具

要使用创建/更新/删除连接器的工具，必须在 .env 文件中定义该特定连接器的凭据。以下是我们支持的连接器的 credentials 列表：

Firecrawl 源

Firecrawl 是一个网络爬虫 API，它在我们的 MCP 中提供了两个主要功能：

1. HTML 内容检索：使用 invoke_firecrawl_crawlhtml 启动爬取任务，并使用 check_crawlhtml_status 监控这些任务
2. 针对大语言模型优化的文本生成：使用 invoke_firecrawl_llmtxt 生成文本，并使用 check_llmtxt_status 获取结果

Firecrawl 的工作原理：

网络爬取过程：

• 从指定的 URL 开始，分析以识别链接
• 如果可用则使用站点地图；否则跟随网站上找到的链接
• 递归遍历每个链接以发现所有子页面
• 从每个访问过的页面收集内容，处理 JavaScript 渲染和速率限制
• 如有需要，可以使用 cancel_crawlhtml_job 取消任务
• 如果你需要将所有提取的信息整理成原始 HTML，Unstructured 的工作流程会很好地清理这些信息 :smile:

LLM 文本生成：

• 爬取后，从爬取的页面中提取干净且有意义的文本内容
• 生成专为大型语言模型格式化的优化文本格式
• 结果会自动上传到指定的 S3 位置
• 注意：一旦开始，LLM 文本生成任务不能被取消。虽然提供了 cancel_llmtxt_job 函数以保持一致性，但目前不被 Firecrawl API 支持。

注意：要使用这些功能，必须设置 FIRECRAWL_API_KEY 环境变量。

Claude 桌面集成

要在 Claude 桌面安装：

1. 前往 ~/Library/Application Support/Claude/ 并创建一个 claude_desktop_config.json 文件。
2. 在该文件中添加：

{
    "mcpServers":
    {
        "UNS_MCP":
        {
            "command": "ABSOLUTE/PATH/TO/.local/bin/uv",
            "args":
            [
                "--directory",
                "ABSOLUTE/PATH/TO/YOUR-UNS-MCP-REPO/uns_mcp",
                "run",
                "server.py"
            ],
            "env":
            [
            "UNSTRUCTURED_API_KEY":"<your key>"
            ],
            "disabled": false
        }
    }
}

1. 重启 Claude Desktop。

2. 从 Claude Desktop 观察到的示例问题。

   • 当你查询目的地连接器列表时，你会看到 No destinations found。请检查 .env 或配置 json 中的 API 密钥，它需要是你在 https://platform.unstructured.io/app/account/api-keys 上的个人密钥。

调试工具

Anthropic 提供了 MCP Inspector 工具来调试/测试你的 MCP 服务器。运行以下命令启动调试界面。从那里，你可以通过左侧窗格添加环境变量（指向你的本地环境）。在那里包括你的个人 API 密钥作为环境变量。转到 tools，你可以测试添加到 MCP 服务器的功能。

mcp dev uns_mcp/server.py

如果你需要记录对 UnstructuredClient 的请求调用参数，请设置环境变量 DEBUG_API_REQUESTS=false。
日志存储在一个格式为 unstructured-client-{date}.log 的文件中，可以检查这个文件来调试对 UnstructuredClient 函数的请求调用参数。

本地运行最小客户端

uv run python minimal_client/client.py uns_mcp/server.py

或者

make local-client

用于配置客户端行为的环境变量：

• LOG_LEVEL="ERROR" # 如果您希望隐藏来自LLM的输出，并为用户提供清晰的消息
• CONFIRM_TOOL_USE='false' 如果您希望在运行工具之前禁用工具使用确认（默认为True）。请注意该选项，因为LLM可能会决定清除您账户中的所有数据或运行一些昂贵的工作流；仅用于开发目的。

本地运行最小客户端，通过HTTP + SSE访问本地MCP服务器

这里的主要区别在于，在开发过程中更容易在服务器端设置断点——客户端和服务器是解耦的。

# in one terminal, run the server:
uv run python uns_mcp/server.py --host 127.0.0.1 --port 8080

or
make sse-server

# in another terminal, run the client:
uv run python minimal_client/client.py "http://127.0.0.1:8080/sse"

or
make sse-client

提示：先用ctrl+c退出客户端，然后再退出服务器。否则服务器似乎会挂起。

CHANGELOG.md

任何新开发的功能/修复/增强都将被添加到CHANGELOG.md中。在我们升级到稳定版本之前，0.x.x-dev 预发布格式是首选。