SpotDraft MCP Server

Integrate the SpotDraft API into agentic workflows via MCP.

This server provides tools to interact with SpotDraft's contract management features.

Tools

Contract Management

1. get_contract_list: Retrieves a list of contracts.
2. get_contract_download_link: Obtains a download link for a contract.
3. get_contract_status: Gets the status of a specific contract.
4. get_contract_activity_log: Retrieves the activity log (comments) for a contract.
5. get_contract_approvals: Fetches approvals for a specific contract.
6. get_contract_key_pointers: Fetches key pointers for a specific contract.

Template Management

7. get_templates: Retrieves a list of contract templates.
8. get_template_details: Fetches details for a specific contract template.
9. get_template_metadata: Fetches metadata for a specific contract template.

Counter Party Management

10. get_counter_parties: Retrieves a list of counter parties.
11. get_counter_party_details: Fetches details for a specific counter party.

Facet Discovery

12. get_workspace_facets: Retrieves available search facets for filtering and searching contracts in the workspace.
13. get_workspace_facet_options: Gets facet options for contract search filtering.

Other Tools

14. get_key_pointers: Retrieves key pointers.
15. get_contract_types: Retrieves available contract types.

Alpha Software Disclaimer

This software is currently in Alpha and is not covered by any support SLA. It should not be used in production environments.

Setup

Prerequisites

• Node.js 20 or higher
• SpotDraft API credentials

Credentials

You will need a Client ID and Client Secret from your SpotDraft account.

Environment Variables

Set the following environment variables before running the server:

• SPOTDRAFT_CLIENT_ID: Your SpotDraft API Client ID.
• SPOTDRAFT_CLIENT_SECRET: Your SpotDraft API Client Secret.
• SPOTDRAFT_BASE_URL (Optional): The base URL for the SpotDraft API. Defaults to https://api.spotdraft.com/api. You might need to change this based on your data residency region (e.g., https://api.us.spotdraft.com/api, https://api.eu.spotdraft.com/api).

Installation & Usage

Option 1: NPX (Recommended)

Usage with Claude Desktop

To use this with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "spotdraft": {
      "command": "npx",
      "args": ["@spotdraft/spotdraft-mcp"],
      "env": {
        "SPOTDRAFT_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "SPOTDRAFT_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "SPOTDRAFT_BASE_URL": "<SPOTDRAFT_BASE_URL>" (optional)
      }
    },
    "streamable-http-spotdraft": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp?baseUrl=https%3A%2F%2Fapi.us.spotdraft.com%2Fapi",
      "note": "For Streamable HTTP connections, add this URL directly in your MCP Client"
    }
  }
}

Direct Usage

npx @spotdraft/spotdraft-mcp

Option 2: Local Development

1. Clone the repository:

git clone https://github.com/spotdraft/spotdraft-mcp.git
cd spotdraft-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Set environment variables and run:

export SPOTDRAFT_CLIENT_ID="your_client_id"
export SPOTDRAFT_CLIENT_SECRET="your_client_secret"
npm start

Option 3: Docker

Build and Run

1. Build the Docker image:

docker build -t spotdraft-mcp .

2. Run in stdio mode (default - for MCP clients):

docker run -e SPOTDRAFT_CLIENT_ID=your_client_id -e SPOTDRAFT_CLIENT_SECRET=your_client_secret spotdraft-mcp

3. Run in HTTP mode (for web access):

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

4. Run with custom port:

docker run -p 8080:8080 -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 --port=8080

Docker Compose (Optional)

Create a docker-compose.yml file:

version: '3.8'
services:
  spotdraft-mcp:
    build: .
    ports:
      - '3000:3000'
    environment:
      - SPOTDRAFT_CLIENT_ID=${SPOTDRAFT_CLIENT_ID}
      - SPOTDRAFT_CLIENT_SECRET=${SPOTDRAFT_CLIENT_SECRET}
      - SPOTDRAFT_BASE_URL=${SPOTDRAFT_BASE_URL}
    command: ['node', 'build/index.js', '--http']

Then run:

docker-compose up

Server Modes

The server supports two modes:

Stdio Mode (Default)

• Used by MCP clients like Claude Desktop
• Communicates over standard input/output
• No network ports required

HTTP Mode

• Provides REST endpoints for web access
• Useful for testing and web integrations
• Includes health check endpoint at /health
• Main MCP endpoint at /mcp

To run in HTTP mode, add the --http flag:

node build/index.js --http

When running in HTTP mode, you can pass the base URL using environment variables:

export SPOTDRAFT_BASE_URL="https://api.us.spotdraft.com/api"
node build/index.js --http

API Endpoints (HTTP Mode)

When running in HTTP mode, the following endpoints are available:

• GET /health - Health check endpoint
• POST /mcp - Main MCP endpoint for tool calls

Development

Scripts

• npm run build - Compile TypeScript
• npm run watch - Watch mode for development
• npm run inspector - Run MCP inspector for debugging

Project Structure

src/
├── index.ts                 # Main server file
├── contract/               # Contract management tools
├── counter_parties/        # Counter party tools
├── key_pointers/          # Key pointers tools
└── templates/             # Template management tools

License

MIT License - see LICENSE file for details.

Support

This is alpha software. For issues and feature requests, please use the GitHub repository.