项目简介

Faxbot MCP 服务器是Faxbot项目的核心组件之一，它将传统的传真功能通过Model Context Protocol (MCP) 标准化，为大型语言模型（LLM）客户端提供上下文服务。这意味着LLM可以像使用内部功能一样，通过调用工具来发送传真、获取传真状态、查看收件箱传真等。它支持Python和Node.js两种实现，并提供Stdio、HTTP和SSE等多种传输协议。

主要功能点

发送传真： 允许LLM向指定号码发送PDF或文本文件作为传真。支持本地文件路径、文件URL或Base64编码的文件内容。
获取传真状态： 查询已发送传真的当前状态、页数、收件人及任何错误信息。
列出收件箱传真： 获取最近收到的传真列表（仅元数据）。
获取传真详情： 根据ID获取特定入站或出站传真的详细信息。
下载入站传真PDF： 以Base64字符串或URL形式获取入站传真的PDF内容。
多种传输协议： 支持Stdio（适用于本地桌面助手）、HTTP和SSE（EventSource，支持OAuth2认证）等。
后端抽象： MCP服务器与Faxbot核心API交互，该API可配置使用Phaxio、Sinch或自托管SIP/Asterisk等多种传真后端服务。

安装步骤 (以Python SSE服务器为例)

在部署Faxbot MCP服务器之前，请确保您已设置并运行了Faxbot核心API服务。MCP服务器将连接到该API服务。

克隆Faxbot仓库：

git clone https://github.com/DMontgomery40/Faxbot.git
cd Faxbot

进入Python MCP目录：
```
cd python_mcp
```

创建并激活Python虚拟环境：

python -m venv .venv
source .venv/bin/activate

安装Python依赖：

pip install -r requirements.txt

配置Faxbot API连接： MCP服务器需要知道如何连接到您的Faxbot核心API。请设置以下环境变量：
- 'FAX_API_URL': 您的Faxbot核心API的基础URL（例如：'http://localhost:8080'）。
```
export FAX_API_URL=http://localhost:8080 
```
- 'API_KEY' (可选): 如果您的Faxbot核心API配置了API密钥，请在此处提供。
```
export API_KEY=your_faxbot_api_key
```
配置OAuth2认证 (仅SSE模式需要，可选): 如果计划使用OAuth2保护您的SSE MCP服务器，请设置以下环境变量。这些值应从您的身份提供商（如Auth0, Okta等）获取。
- 'OAUTH_ISSUER': 您的OIDC颁发者URL（例如：'https://example.auth0.com'）。
- 'OAUTH_AUDIENCE': 预期受众声明（例如：'faxbot-mcp'）。
- 'OAUTH_JWKS_URL': JWKS端点URL（通常是'${OAUTH_ISSUER}/.well-known/jwks.json'）。
```
export OAUTH_ISSUER=https://YOUR_OIDC_ISSUER
export OAUTH_AUDIENCE=faxbot-mcp
export OAUTH_JWKS_URL=https://YOUR_OIDC_ISSUER/.well-known/jwks.json
```

启动Faxbot MCP服务器：

启动SSE服务器 (默认端口3003):

uvicorn server:app --host 0.0.0.0 --port 3003

启动HTTP服务器 (默认端口3004):

uvicorn http_server:app --host 0.0.0.0 --port 3004

启动Stdio服务器 (无特定端口，通过标准输入/输出通信):
```
python stdio_server.py
```

服务器配置 (供LLM客户端连接)

LLM客户端需要以下JSON格式的配置信息才能连接到Faxbot MCP服务器。请根据您实际启动的服务器类型选择对应的配置，并替换占位符。

1. Stdio (标准输入/输出传输协议) 这种模式适用于LLM客户端和MCP服务器在同一台机器上以进程间通信方式运行。

{
  "serverName": "Faxbot Stdio (Python)",
  "command": "python",
  "args": [
    "/path/to/Faxbot/python_mcp/stdio_server.py"
  ],
  "env": {
    "FAX_API_URL": "http://localhost:8080", // Faxbot核心API的地址。请务必根据您的实际部署修改。
    "API_KEY": "your_faxbot_api_key" // 如果Faxbot API需要API密钥，请在此处提供。
  },
  "description": "通过标准输入/输出与本地Faxbot MCP服务器通信，提供传真发送和查询功能。适用于桌面AI助手等场景。"
}

2. HTTP (流式HTTP传输协议) 适用于LLM客户端通过HTTP API调用MCP服务器。此示例不包含OAuth2认证。

{
  "serverName": "Faxbot HTTP (Python)",
  "command": "http",
  "args": [
    "http://localhost:3004/mcp" // Faxbot MCP HTTP服务器的完整URL路径。请务必根据您的实际部署修改主机和端口。
  ],
  "headers": {
    "X-API-Key": "YOUR_MCP_HTTP_API_KEY" // 如果您的Faxbot MCP HTTP服务器配置了API密钥 (通过MCP_HTTP_API_KEY环境变量)，请在此处提供。
  },
  "description": "通过HTTP协议与Faxbot MCP服务器通信，提供传真发送和查询功能。通常需要一个API密钥进行认证。"
}

3. SSE (Server-Sent Events 传输协议，支持OAuth2) 适用于LLM客户端需要通过长连接和OAuth2/JWT进行安全认证的场景。

{
  "serverName": "Faxbot SSE (Python)",
  "command": "sse",
  "args": [
    "http://localhost:3003/sse" // Faxbot MCP SSE服务器的完整URL路径。请务必根据您的实际部署修改主机和端口。
  ],
  "auth": {
    "type": "oauth2",
    "token": "YOUR_OAUTH2_BEARER_TOKEN" // LLM客户端需要在此处提供有效的OAuth2 Bearer Token。
  },
  "description": "通过SSE协议与Faxbot MCP服务器通信，支持OAuth2/JWT认证，提供传真发送和查询功能。这是推荐的生产环境安全连接方式。"
}

基本使用方法

一旦LLM客户端通过上述配置成功连接到Faxbot MCP服务器，它就可以通过JSON-RPC协议调用服务器暴露的工具和访问资源。LLM可以根据用户的需求，自动选择和调用相应的工具。

示例工具调用 (LLM客户端视角):

发送传真： LLM客户端可能会将用户请求转换为如下工具调用：

user: 请帮我将这份报告发送到传真号码 +15551234567。报告文件路径是 /home/user/report.pdf。
assistant: (调用工具: send_fax, arguments: { "to": "+15551234567", "filePath": "/home/user/report.pdf" })

查询传真状态： LLM客户端根据用户提供的传真任务ID，调用查询工具：

user: 我之前发送的传真 fbja_abc123 现在状态如何？
assistant: (调用工具: get_fax_status, arguments: { "jobId": "fbja_abc123" })

获取入站传真列表： LLM客户端根据用户需求调用列表工具：

user: 请列出最近收到的传真。
assistant: (调用工具: list_inbound)

关键词

项目简介

主要功能点

安装步骤 (以Python SSE服务器为例)

服务器配置 (供LLM客户端连接)

基本使用方法

信息