Spotdraft MCP

SpotDraft MCP服务器

通过MCP将SpotDraft API集成到代理工作流中。

npm： ](https://www.npmjs.com/package/@spotdraft/spotdraft-mcp) --发行说明： 更改日志.md.

阿尔法软件 --不在任何支持SLA的覆盖范围内。请勿在生产中使用。

工具

合同管理

• get_contract_list --列出合同（筛选器包括 contract_id 和 $eq / $in 对于一个或多个复合ID）
• get_contract_download_link --获取合同下载链接
• get_contract_status --获取合同状态
• get_contract_activity_log --获取活动日志（评论）
• get_contract_approvals --获得合同批准
• get_contract_key_pointers --获取合约密钥指针

写入工具（需要写入模式）

这些工具仅在启用写入模式时列出并可调用（请参阅 写入功能):

• upload_contract_version --上传现有合同的新合同版本（PDF）
• send_contract_to_counterparties --通过电子邮件将合同发送给交易对手
• create_contract_approvals --创建并发送合同的临时审批请求
• add_contract_comment --在合同活动日志中添加注释

模板管理

• get_templates --列出模板
• get_template_details --获取模板详细信息
• get_template_metadata --获取模板元数据

交易对手管理

• get_counter_parties --列出交易对手
• get_counter_party_details --获取交易对手详细信息

面部发现

• get_workspace_facets --检索可用的搜索方面，以便在工作区中筛选和搜索合同
• get_workspace_facet_options --获取合约搜索筛选的方面选项

法律招生管理

• get_legal_intakes --列出所有合法入境者
• get_legal_intake_by_id --通过id获取特定的合法收入

其他

• get_key_pointers --检索关键指针
• get_contract_types --检索可用的合约类型

设置

先决条件

• Node.js 20+
• SpotDraft API凭据（客户端ID和客户端机密）

环境变量

必需（标准模式）

必需（HTTP模式）

可选的

OAuth 2.0（可选——启用 OAuth支持)

安装与使用

选项1:NPX（推荐）

npx @spotdraft/spotdraft-mcp

克劳德桌面——标准模式

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "spotdraft": {
      "command": "npx",
      "args": ["@spotdraft/spotdraft-mcp"],
      "env": {
        "SPOTDRAFT_CLIENT_ID": "",
        "SPOTDRAFT_CLIENT_SECRET": "",
        "SPOTDRAFT_BASE_URL": ""
      }
    }
  }
}

克劳德桌面——HTTP模式

使用单独启动服务器 node build/index.js --http，然后添加：

{
  "mcpServers": {
    "streamable-http-spotdraft": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp?baseUrl=https%3A%2F%2Fapi.us.spotdraft.com%2Fapi"
    }
  }
}

要启用编写工具（上传版本、发送合同、批准、评论），请附加 &enable_write=true 到URL或设置 SD_MCP_ENABLE_WRITE=true 在服务器环境中。

方案2：地方发展

git clone https://github.com/spotdraft/spotdraft-mcp.git
cd spotdraft-mcp
npm install
npm run build
export SPOTDRAFT_CLIENT_ID="your_client_id"
export SPOTDRAFT_CLIENT_SECRET="your_client_secret"
# Required: set SERVER_PUBLIC_URL or startup fails with ZodError (server.publicUrl expected string, received undefined)
export SERVER_PUBLIC_URL="http://localhost:3000"
npm start

对于HTTP模式，请从以下内容开始： SERVER_PUBLIC_URL=http://localhost:3000 node build/index.js --http （或在前面设置env变量 npm start 并通过 --http).

选项3:Docker

# Build
docker build -t spotdraft-mcp .

# Run — stdio mode (default)
docker run -e SPOTDRAFT_CLIENT_ID=your_client_id -e SPOTDRAFT_CLIENT_SECRET=your_client_secret spotdraft-mcp

# Run — HTTP mode
docker run -p 3000:3000 \
  -e SPOTDRAFT_CLIENT_ID=your_client_id \
  -e SPOTDRAFT_CLIENT_SECRET=your_client_secret \
  -e SPOTDRAFT_BASE_URL=https://api.us.spotdraft.com/api \
  spotdraft-mcp node build/index.js --http

服务器模式

标准（默认） --由Claude Desktop等MCP客户端使用。通过stdin/stdout进行通信。日志以JSON格式发送到stderr。

超文本传输协议 (--http flag）--公开用于web集成的REST端点。日志以人类可读的格式发送到stdout。

写入功能

编写工具(upload_contract_version, send_contract_to_counterparties, create_contract_approvals, add_contract_comment)都是 默认情况下禁用。它们仅列在 tools/list 并且仅在写入模式打开时可执行。

启用写入模式

• HTTP模式 --使用以下任一方法：

- 查询参数：调用MCP URL enable_write=true （例如。 http://localhost:3000/mcp?enable_write=true 或 .../mcp?baseUrl=...&enable_write=true)，或 - 环境变量：set SD_MCP_ENABLE_WRITE=true （或 1 / yes，不区分大小写）启动服务器时。

• 标准模式 --设置 SD_MCP_ENABLE_WRITE=true （或 1 / yes)在服务器运行的环境中（例如在Claude Desktop配置中 env).

如果客户端在写模式关闭时调用写工具，服务器将以 403 和错误代码 WRITE_DISABLED 以及一条解释如何启用写入的消息。

TOON响应格式

成功的工具调用默认在MCP内容块内返回JSON文本。要为每次成功的工具调用请求TOON文本，请启用TOON模式：

• HTTP模式 --添加 response_format=toon 指向MCP URL，例如。 http://localhost:3000/mcp?response_format=toon.
• 标准模式 --设置 SD_MCP_RESPONSE_FORMAT=toon 在服务器运行的环境中。

在这两种模式下，外部MCP/JSON-RPC响应都是JSON。仅 result.content[].text 在JSON文本和TOON文本之间切换。

OAuth 2.0授权

可选的 MCP授权规范 兼容OAuth 2.0支持。服务器充当OAuth 2.0受保护资源（RFC 9728）。

OAuth是完全向后兼容的——现有的Basic Auth集成继续工作。

身份验证方法

基本认证 --发送 clientId:clientSecret 作为Bearer代币：

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer clientId:clientSecret" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

OAuth承载令牌 --从授权服务器发送JWT：

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

服务器自动检测：包含以下内容的令牌 : 使用基本身份验证；JWT格式的令牌（3个点分隔的部分）使用OAuth。

受保护资源元数据

当 OAUTH_AUTHORIZATION_SERVER_URL 设置后，服务器将公开：

GET /.well-known/oauth-protected-resource

{
  "resource": "https://your-mcp-server.com",
  "authorization_servers": ["https://your-auth-server.com"],
  "resource_name": "SpotDraft MCP Server"
}

配置示例

生产：

SERVER_PUBLIC_URL=https://mcp.spotdraft.com
OAUTH_AUTHORIZATION_SERVER_URL=https://api.spotdraft.com
OAUTH_JWKS_URI=https://api.spotdraft.com/.well-known/jwks.json
OAUTH_AUDIENCE=https://mcp.spotdraft.com
SPOTDRAFT_BASE_URL=https://api.spotdraft.com/api

发展：

SERVER_PUBLIC_URL=http://localhost:3000
OAUTH_AUTHORIZATION_SERVER_URL=http://localhost:8000/api/v1/oauth
OAUTH_JWKS_URI=https://api.dev.spotdraft.com/.well-known/jwks.json
OAUTH_AUDIENCE=https://api.spotdraft.com
SPOTDRAFT_BASE_URL=https://api.in.dev.spotdraft.com/api

发展

npm run build       # Compile TypeScript
npm run watch       # Watch mode
npm run inspector   # MCP inspector for debugging

项目结构

src/
├── index.ts                 # Entry point
├── handler.ts               # Shared request handlers
├── spotdraft_client.ts      # API client
├── auth/                    # Authentication
├── errors/                  # Error types
├── logging/                 # Logging
├── validation/              # Input validation
├── servers/                 # HTTP and stdio servers
└── tools/                   # Tool implementations
    ├── contracts/
    ├── contract-types/
    ├── counter-parties/
    ├── facets/
    ├── key-pointers/
    └── templates/

更新日志

版本历史和迁移说明： 更改日志.md.

许可证

麻省理工学院——见 许可证.