Unstructured API MCP Server

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

可用工具

工具	描述
list_sources	列出Unstructured API中的可用数据源。
get_source_info	获取特定数据源连接器的详细信息。
create_source_connector	创建数据源连接器。
update_source_connector	根据参数更新现有的数据源连接器。
delete_source_connector	根据数据源ID删除数据源连接器。
list_destinations	列出Unstructured API中的可用目标。
get_destination_info	获取特定目标连接器的详细信息。
create_destination_connector	根据参数创建目标连接器。
update_destination_connector	根据目标ID更新现有的目标连接器。
delete_destination_connector	根据目标ID删除目标连接器。
list_workflows	列出Unstructured API中的工作流。
get_workflow_info	获取特定工作流的详细信息。
create_workflow	使用源、目标ID等创建新的工作流。
run_workflow	运行具有工作流ID的特定工作流。
update_workflow	根据参数更新现有工作流。
delete_workflow	根据ID删除特定的工作流。
list_jobs	列出特定工作流的所有作业。
get_job_info	根据作业ID获取特定作业的详细信息。
cancel_job	根据作业ID删除特定作业。
list_workflows_with_finished_jobs	列出所有具有已完成作业的工作流，以及有关源和目标的详细信息。

以下是UNS-MCP服务器当前支持的连接器列表，请参阅Unstructured平台支持的完整源连接器列表这里和目标列表这里。我们计划添加更多！

源	目标
S3	S3
Azure	Weaviate
Google Drive	Pinecone
OneDrive	AstraDB
Salesforce	MongoDB
Sharepoint	Neo4j
	Databricks Volumes
	Databricks Volumes Delta

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

凭证名称	描述
ANTHROPIC_API_KEY	需要运行minimal_client以与我们的服务器交互。
AWS_KEY, AWS_SECRET	需要通过uns-mcp服务器创建S3连接器，参见文档和这里。
WEAVIATE_CLOUD_API_KEY	需要通过uns-mcp服务器创建Weaviate向量数据库连接器，参见文档。
FIRECRAWL_API_KEY	需要使用external/firecrawl.py中的Firecrawl工具，注册Firecrawl并获取API密钥。
ASTRA_DB_APPLICATION_TOKEN, ASTRA_DB_API_ENDPOINT	需要通过uns-mcp服务器创建AstraDB连接器，参见文档。
AZURE_CONNECTION_STRING	创建Azure连接器的第一种方式，参见文档。
AZURE_ACCOUNT_NAME+AZURE_ACCOUNT_KEY	创建Azure连接器的第二种方式，参见文档。
AZURE_ACCOUNT_NAME+AZURE_SAS_TOKEN	创建Azure连接器的第三种方式，参见文档。
NEO4J_PASSWORD	需要通过uns-mcp服务器创建Neo4j连接器，参见文档。
MONGO_DB_CONNECTION_STRING	需要通过uns-mcp服务器创建MongoDB连接器，参见文档。
GOOGLEDRIVE_SERVICE_ACCOUNT_KEY	字符串值。原始服务器账户密钥（遵循文档）位于json文件中，在终端中运行base64 < /path/to/google_service_account_key.json以获取字符串值。
DATABRICKS_CLIENT_ID,DATABRICKS_CLIENT_SECRET	需要通过uns-mcp服务器创建Databricks卷/增量表连接器，参见文档和这里。
ONEDRIVE_CLIENT_ID, ONEDRIVE_CLIENT_CRED,ONEDRIVE_TENANT_ID	需要通过uns-mcp服务器创建OneDrive连接器，参见文档。
PINECONE_API_KEY	需要通过uns-mcp服务器创建Pinecone向量数据库连接器，参见文档。
SALESFORCE_CONSUMER_KEY,SALESFORCE_PRIVATE_KEY	需要通过uns-mcp服务器创建Salesforce源连接器，参见文档。
SHAREPOINT_CLIENT_ID, SHAREPOINT_CLIENT_CRED,SHAREPOINT_TENANT_ID	需要通过uns-m-服务器创建Sharepoint连接器，参见文档。
LOG_LEVEL	用于设置minimal_client的日志级别，例如设置为ERROR以获取所有内容。
CONFIRM_TOOL_USE	设置为true以便minimal_client可以在每次调用工具前确认执行。
DEBUG_API_REQUESTS	设置为true以便uns_mcp/server.py可以输出请求参数以进行更好的调试。

Firecrawl 源

Firecrawl是一个网络爬取API，它在我们的MCP中有两个主要功能：

1. HTML内容检索：使用invoke_firecrawl_crawlhtml启动爬取任务，并使用check_crawlhtml_status监控它们。
2. LLM优化文本生成：使用invoke_firecrawl_llmtxt生成文本，并使用check_llmtxt_status检索结果。

Firecrawl的工作原理：

网络爬取过程：

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

LLM文本生成：

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

注意：必须设置一个FIRECRAWL_API_KEY环境变量才能使用这些功能。

安装与配置

本指南提供了分步说明，以使用Python 3.12和uv工具设置和配置UNS_MCP服务器。

先决条件

• Python 3.12+
• uv用于环境管理
• 来自Unstructured的API密钥。您可以在这里注册并获得您的API密钥。

使用uv（推荐）

当使用uvx时不需要额外安装，因为它处理了执行。但是，如果您希望直接安装包：

uv pip install uns_mcp

配置Claude Desktop

为了与Claude Desktop集成，在您的claude_desktop_config.json中添加以下内容：

注意： 文件位于~/Library/Application Support/Claude/目录下。

使用uvx命令：

{
   "mcpServers": {
      "UNS_MCP": {
         "command": "uvx",
         "args": ["uns_mcp"],
         "env": {
           "UNSTRUCTURED_API_KEY": "<your-key>"
         }
      }
   }
}

或者，使用Python包：

{
   "mcpServers": {
      "UNS_MCP": {
         "command": "python",
         "args": ["-m", "uns_mcp"],
         "env": {
           "UNSTRUCTURED_API_KEY": "<your-key>"
         }
      }
   }
}

使用源代码

1. 克隆存储库。
2. 安装依赖项：

   uv sync
   

3. 将您的Unstructured API密钥设置为环境变量。在根目录中创建一个.env文件，内容如下：

   UNSTRUCTURED_API_KEY="YOUR_KEY"
   

   参考.env.template了解可配置的环境变量。

现在，您可以使用以下方法之一运行服务器：

<details> <summary> 使用可编辑包安装 </summary> 作为可编辑包安装： ```bash uvx pip install -e . ```

更新您的Claude Desktop配置：

{
  "mcpServers": {
    "UNS_MCP": {
      "command": "uvx",
      "args": ["uns_mcp"]
    }
  }
}

注意：记得指向已安装包的环境中的uvx可执行文件。

</details> <details> <summary> 使用SSE服务器协议 </summary>

注意：不被Claude Desktop支持。

对于SSE协议，您可以通过分离客户端和服务器来更轻松地调试：

1. 在一个终端中启动服务器：

   uv run python uns_mcp/server.py --host 127.0.0.1 --port 8080
   # 或者
   make sse-server
   

2. 在另一个终端中使用本地客户端测试服务器：

   uv run python minimal_client/client.py "http://127.0.0.1:8080/sse"
   # 或者
   make sse-client
   

注意：要停止服务，请先在客户端使用Ctrl+C，然后在服务器上使用。

</details> <details> <summary> 使用Stdio服务器协议 </summary>

配置Claude Desktop以使用stdio：

{
  "mcpServers": {
    "UNS_MCP": {
      "command": "ABSOLUTE/PATH/TO/.local/bin/uv",
      "args": [
        "--directory",
        "ABSOLUTE/PATH/TO/YOUR-UNS-MCP-REPO/uns_mcp",
        "run",
        "server.py"
      ]
    }
  }
}

或者，运行本地客户端：

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

</details>

额外的本地客户端配置

使用环境变量配置最小客户端：

• LOG_LEVEL="ERROR"：设置以抑制来自LLM的调试输出，显示清晰的消息给用户。
• CONFIRM_TOOL_USE='false'：禁用工具使用确认前的执行。谨慎使用，特别是在开发期间，因为LLM可能会执行昂贵的工作流或删除数据。

调试工具

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

mcp dev uns_mcp/server.py

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

添加终端访问到最小客户端

我们将使用@wonderwhy-er/desktop-commander为最小客户端添加终端访问。它是基于MCP文件系统服务器构建的。请注意，客户端（也包括LLM）现在有权访问私有文件。

执行以下命令以安装包：

npx @wonderwhy-er/desktop-commander setup

然后使用额外参数启动客户端：

uv run python minimal_client/client.py "http://127.0.0.1:8080/sse" "@wonderwhy--er/desktop-commander@^0.2.11"
# 或者
make sse-client-terminal

使用部分工具

如果您的客户端仅支持使用部分工具，那么您应该注意以下事项：

• update_workflow工具必须与create_workflow工具一起加载到上下文中，因为前者包含了如何创建和配置自定义节点的详细描述。

已知问题

• update_workflow - 需要在上下文中提供要更新的工作流的配置，要么由用户提供，要么通过调用get_workflow_info工具，因为此工具不是patch应用程序，而是完全替换工作流配置。

CHANGELOG.md

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

故障排除

• 如果遇到Error: spawn <command> ENOENT错误，这意味着<command>未安装或不在您的PATH中：
  • 确保已安装并将其添加到您的PATH中。
  • 或者在配置的command字段中提供命令的绝对路径。例如，将python替换为/opt/miniconda3/bin/python。