dferranti/wealthbox-mcp

Wealthbox MCP Server

A lightweight MCP (Model-Controller-Proxy) Server built with Rails that provides a clean JSON interface for AI clients to interact with the Wealthbox API.

Features

• Natural Language Processing: Submit queries in natural language and get structured responses
• Resource Access: Direct access to Wealthbox resources by ID
• Generic Actions: Execute predefined actions like creating notes, fetching opportunities
• CORS Support: Ready for cross-origin requests from web applications
• Error Handling: Structured error responses with proper HTTP status codes

Setup

Prerequisites

• Ruby 3.2+
• Rails 8.0+
• Bundler

Installation

1. Clone the repository

git clone <repository-url>
cd wealthbox_mcp_server

2. Install dependencies

bundle install

3. Set up environment variables

cp .env.example .env
# Edit .env with your Wealthbox API key

4. Start the server

rails server

The server will be available at http://localhost:3000

Configuration

Environment Variables

• WEALTHBOX_API_KEY: Your Wealthbox API key (required)
• WEALTHBOX_BASE_URL: Wealthbox API base URL (default: https://dev.wealthbox.com/api)
• RAILS_ENV: Rails environment (development/production)

API Endpoints

POST /query

Process natural language queries and return structured responses.

Request:

{
  "role": "user",
  "input": "Get last 5 notes for Acme",
  "context": {
    "user_id": "xyz",
    "account_id": "abc"
  }
}

Response:

{
  "status": "ok",
  "result": "Found notes for Acme",
  "raw": {
    "data": [...]
  }
}

Supported Natural Language Patterns:

• "Get notes for [entity name]"
• "Find opportunities tagged '[tag]'"
• "Get last [number] contacts"

GET /resource/:id

Retrieve a specific Wealthbox resource by ID.

Example:

curl http://localhost:3000/resource/contact-456

Response:

{
  "status": "ok",
  "result": "Resource contact-456 retrieved",
  "raw": {
    "data": {...}
  }
}

POST /action

Execute predefined actions on Wealthbox resources.

Request:

{
  "action": "create_note",
  "entity_id": 123,
  "text": "Follow-up scheduled."
}

Response:

{
  "status": "ok",
  "result": "Note created successfully",
  "raw": {
    "data": {...}
  }
}

Supported Actions:

• create_note: Create a new note
• fetch_opportunity: Get opportunity details
• update_contact: Update contact information

Health Check Endpoints

• GET /healthz: Service health status
• GET /version: API version information

Testing

Sample Requests

1. Natural Language Query:

curl -X POST http://localhost:3000/query \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Get all notes for Acme Corporation",
    "context": {"user_id": "123"}
  }'

2. Resource Access:

curl http://localhost:3000/resource/contact-456

3. Action Execution:

curl -X POST http://localhost:3000/action \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_note",
    "entity_id": 123,
    "text": "Meeting scheduled for next week"
  }'

4. Health Check:

curl http://localhost:3000/healthz

Error Handling

All endpoints return structured error responses:

{
  "status": "error",
  "error": "Invalid access token or expired session."
}

Common HTTP status codes:

• 400: Bad Request (missing parameters)
• 401: Unauthorized (invalid API key)
• 404: Not Found (resource doesn't exist)
• 500: Internal Server Error

Development

Adding New Actions

To add a new action, update the execute_action method in app/controllers/mcp_controller.rb:

def execute_action(action_name, params)
  case action_name
  when 'your_new_action'
    your_new_action_method(params)
  # ... existing actions
  end
end

private

def your_new_action_method(params)
  # Implementation here
  {
    message: "Action completed",
    data: result_data
  }
end

Extending Natural Language Processing

Update the parse_natural_language method to recognize new patterns:

def parse_natural_language(input)
  input_lower = input.downcase
  
  if input_lower.include?('your_keyword')
    # Parse and return intent
    { type: 'your_action', params: extracted_params }
  end
  # ... existing patterns
end

Deployment

Production Configuration

1. Set environment to production:

export RAILS_ENV=production

2. Configure SSL/HTTPS in production environment
3. Set up proper logging and monitoring
4. Use a production-ready web server (Puma, Unicorn)

Docker Deployment

The application includes a Dockerfile for containerized deployment:

docker build -t wealthbox-mcp-server .
docker run -p 3000:3000 -e WEALTHBOX_API_KEY=your_key wealthbox-mcp-server

License

This project is licensed under the MIT License.

Support

For issues and questions, please refer to the Wealthbox API documentation at https://dev.wealthbox.com/