Raworc MCP Server

A production-ready Model Context Protocol (MCP) server for Raworc, enabling AI assistants to seamlessly interact with Raworc's agent runtime platform.

🚀 Quick Start

Option 1: Install via npx (Recommended)

# Test the installation
npx @raworc/mcp-server --help

# Use directly with Claude Desktop
npx @raworc/mcp-server

Option 2: Install from Source

# Clone the repository
git clone https://github.com/harshapalnati/raworc-mcpserver.git
cd raworc-mcpserver

# Build the project
cargo build --release

# Test the installation
./target/release/raworc-mcp --help

📋 Prerequisites

• Rust: Version 1.70 or higher
• Node.js: Version 16.0 or higher (for npx installation)
• Raworc Account: Access to Raworc platform
• Network Access: Ability to reach api.remoteagent.com

🔧 Configuration

Environment Variables

Variable	Description	Default	Required
RAWORC_API_URL	Raworc API base URL	https://api.remoteagent.com/api/v0	No
RAWORC_AUTH_TOKEN	JWT authentication token	-	Yes
RAWORC_DEFAULT_SPACE	Default space for operations	-	No
RAWORC_TIMEOUT	Request timeout in seconds	30	No
LOG_LEVEL	Logging level	info	No

Getting Your Authentication Token

curl -X POST https://api.remoteagent.com/api/v0/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "user": "your-username",
    "pass": "your-password"
  }'

🎯 Features

• Complete API Coverage: Full access to all Raworc REST API endpoints
• Service Account Management: Create, update, and manage service accounts with role-based access
• Role-Based Access Control (RBAC): Manage roles and role bindings for fine-grained permissions
• Space Management: Create, update, and manage isolated workspaces
• Session Management: Create, pause, resume, terminate, and fork sessions
• Message Handling: Send, retrieve, and manage session messages
• Agent Operations: Deploy, monitor, control, and manage agents with full lifecycle support
• Secret Management: Secure storage and retrieval of secrets with proper access controls
• Build Management: Trigger and monitor space builds for agent deployment
• Real-time Communication: Send messages and receive responses from agents
• Health Monitoring: Check API health and version information
• Production Ready: Robust error handling, logging, and MCP protocol compliance

🔌 Claude Desktop Integration

Add the MCP server to your Claude Desktop configuration:

{
  "mcpServers": {
    "raworc": {
      "command": "npx",
      "args": ["@raworc/mcp-server"],
      "env": {
        "RAWORC_API_URL": "https://api.remoteagent.com/api/v0",
        "RAWORC_AUTH_TOKEN": "your-jwt-token",
        "RAWORC_DEFAULT_SPACE": "your-space",
        "RAWORC_TIMEOUT": "30",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Alternative: Direct Binary Path

{
  "mcpServers": {
    "raworc": {
      "command": "/path/to/raworc-mcp",
      "env": {
        "RAWORC_API_URL": "https://api.remoteagent.com/api/v0",
        "RAWORC_AUTH_TOKEN": "your-jwt-token",
        "RAWORC_DEFAULT_SPACE": "your-space"
      }
    }
  }
}

🛠️ Available Tools

The MCP server provides comprehensive access to all Raworc API endpoints. Here are the available tools organized by category:

System Information

health_check

Check Raworc API health status.

{
  "name": "health_check",
  "arguments": {}
}

get_version

Get Raworc API version information.

{
  "name": "get_version",
  "arguments": {}
}

Service Account Management

list_service_accounts

List all service accounts.

{
  "name": "list_service_accounts",
  "arguments": {}
}

create_service_account

Create a new service account.

{
  "name": "create_service_account",
  "arguments": {
    "user": "api-user",
    "pass": "secure-password",
    "space": "production",
    "description": "API access user"
  }
}

get_service_account

Get a specific service account by ID.

{
  "name": "get_service_account",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

update_service_account

Update a service account.

{
  "name": "update_service_account",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "space": "production",
    "description": "Updated description",
    "active": true
  }
}

delete_service_account

Delete a service account.

{
  "name": "delete_service_account",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

update_service_account_password

Update service account password.

{
  "name": "update_service_account_password",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "current_password": "old-password",
    "new_password": "new-secure-password"
  }
}

Role Management

list_roles

List all RBAC roles.

{
  "name": "list_roles",
  "arguments": {}
}

create_role

Create a new role.

{
  "name": "create_role",
  "arguments": {
    "id": "developer",
    "description": "Developer role",
    "rules": [
      {
        "apiGroups": [""],
        "resources": ["sessions", "messages"],
        "verbs": ["get", "list", "create"]
      }
    ]
  }
}

get_role

Get a specific role by ID.

{
  "name": "get_role",
  "arguments": {
    "id": "developer"
  }
}

delete_role

Delete a role.

{
  "name": "delete_role",
  "arguments": {
    "id": "developer"
  }
}

Role Binding Management

list_role_bindings

List all role bindings.

{
  "name": "list_role_bindings",
  "arguments": {}
}

create_role_binding

Create a new role binding.

{
  "name": "create_role_binding",
  "arguments": {
    "subject": "api-user",
    "role_ref": "developer",
    "space": "staging"
  }
}

get_role_binding

Get a specific role binding by ID.

{
  "name": "get_role_binding",
  "arguments": {
    "id": "admin-binding"
  }
}

delete_role_binding

Delete a role binding.

{
  "name": "delete_role_binding",
  "arguments": {
    "id": "admin-binding"
  }
}

Space Management

list_spaces

List all spaces.

{
  "name": "list_spaces",
  "arguments": {}
}

create_space

Create a new space.

{
  "name": "create_space",
  "arguments": {
    "name": "staging",
    "description": "Staging environment",
    "settings": {
      "environment": "staging"
    }
  }
}

get_space

Get a specific space by name.

{
  "name": "get_space",
  "arguments": {
    "name": "staging"
  }
}

update_space

Update a space.

{
  "name": "update_space",
  "arguments": {
    "name": "staging",
    "description": "Updated staging space"
  }
}

delete_space

Delete a space.

{
  "name": "delete_space",
  "arguments": {
    "name": "staging"
  }
}

Session Management

list_sessions

List all sessions in a space.

{
  "name": "list_sessions",
  "arguments": {
    "space": "production"
  }
}

create_session

Create a new session.

{
  "name": "create_session",
  "arguments": {
    "space": "development",
    "metadata": {
      "purpose": "testing",
      "user": "developer"
    }
  }
}

get_session

Get session details by ID.

{
  "name": "get_session",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "space": "production"
  }
}

update_session

Update session details.

{
  "name": "update_session",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "space": "production"
  }
}

update_session_state

Update session state.

{
  "name": "update_session_state",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "state": "closed"
  }
}

close_session

Close a session.

{
  "name": "close_session",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d"
  }
}

restore_session

Restore a closed session.

{
  "name": "restore_session",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d"
  }
}

remix_session

Fork a session.

{
  "name": "remix_session",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "space": "development"
  }
}

pause_session

Pause a session.

{
  "name": "pause_session",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "space": "production"
  }
}

resume_session

Resume a paused session.

{
  "name": "resume_session",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "space": "production"
  }
}

terminate_session

Terminate a session.

{
  "name": "terminate_session",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "space": "production"
  }
}

Session Message Management

get_messages

Get messages from a session.

{
  "name": "get_messages",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "space": "production",
    "limit": 10
  }
}

send_message

Send a message to a session.

{
  "name": "send_message",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "space": "production",
    "content": "Generate a Python script to calculate fibonacci numbers"
  }
}

get_message_count

Get message count for a session.

{
  "name": "get_message_count",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "space": "production"
  }
}

clear_messages

Clear all messages from a session.

{
  "name": "clear_messages",
  "arguments": {
    "session_id": "61549530-3095-4cbf-b379-cd32416f626d",
    "space": "production"
  }
}

Agent Management

list_agents

List agents in a space.

{
  "name": "list_agents",
  "arguments": {
    "space": "production"
  }
}

create_agent

Create a new agent.

{
  "name": "create_agent",
  "arguments": {
    "space": "production",
    "name": "data-analyzer",
    "description": "Data analysis specialist",
    "purpose": "analyze data, create visualizations, statistical analysis",
    "source_repo": "Raworc/raworc-agent-python-demo",
    "source_branch": "main"
  }
}

get_agent

Get a specific agent.

{
  "name": "get_agent",
  "arguments": {
    "space": "production",
    "agent_name": "data-analyzer"
  }
}

update_agent

Update an agent.

{
  "name": "update_agent",
  "arguments": {
    "space": "production",
    "agent_name": "data-analyzer",
    "description": "Updated data analysis specialist",
    "purpose": "enhanced data analysis and visualization"
  }
}

delete_agent

Delete an agent.

{
  "name": "delete_agent",
  "arguments": {
    "space": "production",
    "agent_name": "data-analyzer"
  }
}

update_agent_status

Update agent status.

{
  "name": "update_agent_status",
  "arguments": {
    "space": "production",
    "agent_name": "data-analyzer",
    "status": "inactive"
  }
}

deploy_agent

Deploy an agent.

{
  "name": "deploy_agent",
  "arguments": {
    "space": "production",
    "agent_name": "data-analyzer"
  }
}

stop_agent

Stop an agent.

{
  "name": "stop_agent",
  "arguments": {
    "space": "production",
    "agent_name": "data-analyzer"
  }
}

list_running_agents

List running agents in a space.

{
  "name": "list_running_agents",
  "arguments": {
    "space": "production"
  }
}

get_agent_logs

Get logs for a specific agent.

{
  "name": "get_agent_logs",
  "arguments": {
    "space": "production",
    "agent_name": "data-analyzer",
    "limit": 100,
    "follow": false
  }
}

Secret Management

list_secrets

List secrets in a space.

{
  "name": "list_secrets",
  "arguments": {
    "space": "production",
    "show_values": false
  }
}

create_secret

Create a new secret.

{
  "name": "create_secret",
  "arguments": {
    "space": "production",
    "key_name": "ANTHROPIC_API_KEY",
    "value": "sk-ant-your-actual-key",
    "description": "Claude API key"
  }
}

get_secret

Get a specific secret.

{
  "name": "get_secret",
  "arguments": {
    "space": "production",
    "key": "ANTHROPIC_API_KEY",
    "show_values": true
  }
}

update_secret

Update a secret.

{
  "name": "update_secret",
  "arguments": {
    "space": "production",
    "key": "ANTHROPIC_API_KEY",
    "value": "new-secret-value",
    "description": "Updated description"
  }
}

delete_secret

Delete a secret.

{
  "name": "delete_secret",
  "arguments": {
    "space": "production",
    "key": "ANTHROPIC_API_KEY"
  }
}

Build Management

create_build

Trigger a space build.

{
  "name": "create_build",
  "arguments": {
    "space": "production",
    "dockerfile": "Dockerfile"
  }
}

get_latest_build

Get latest build status.

{
  "name": "get_latest_build",
  "arguments": {
    "space": "production"
  }
}

get_build

Get specific build status.

{
  "name": "get_build",
  "arguments": {
    "space": "production",
    "build_id": "build-550e8400-e29b-41d4-a716-446655440000"
  }
}

🧪 Testing

Quick Test

# Test with npx
npx @raworc/mcp-server --help

# Test health check
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "health_check", "arguments": {}}}' | npx @raworc/mcp-server

# Test list spaces
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "list_spaces", "arguments": {}}}' | npx @raworc/mcp-server

Manual API Testing

# Health check
curl -H "Authorization: Bearer your-token" https://api.remoteagent.com/api/v0/health

# Get version
curl -H "Authorization: Bearer your-token" https://api.remoteagent.com/api/v0/version

# List spaces
curl -H "Authorization: Bearer your-token" https://api.remoteagent.com/api/v0/spaces

🏗️ Development

Building from Source

# Clone the repository
git clone https://github.com/harshapalnati/raworc-mcpserver.git
cd raworc-mcpserver

# Build the project
cargo build --release

# Run tests
cargo test

# Install with npm (for npx distribution)
npm install

Project Structure

raworc-mcpserver/
├── src/
│   ├── main.rs          # Entry point
│   ├── lib.rs           # Library exports
│   ├── client.rs        # Raworc API client
│   ├── error.rs         # Error handling
│   ├── models.rs        # Data models
│   └── mcp.rs           # MCP server implementation
├── bin/
│   └── raworc-mcp.js    # JavaScript wrapper for npx
├── scripts/
│   └── postinstall.js   # Build script for npm installation
├── tests/
│   └── integration_test.rs  # Integration tests
├── examples/
│   ├── claude-desktop-config.json  # Example Claude Desktop config
│   └── usage-example.md            # Usage examples
├── Cargo.toml           # Rust dependencies
├── package.json         # npm package configuration
├── QUICKSTART.md        # Quick start guide
├── TESTING.md           # Testing guide
└── README.md           # This file

🐛 Troubleshooting

Common Issues

1. Authentication Failed

   • Verify your token is valid and not expired
   • Check that you have the correct permissions

2. Connection Issues

   • Verify you can reach api.remoteagent.com
   • Check your network connectivity

3. Permission Errors

   • Ensure your account has the necessary permissions
   • Check that you're using the correct space

Debug Mode

export LOG_LEVEL="debug"
export RAWORC_API_URL="https://api.remoteagent.com/api/v0"
export RAWORC_AUTH_TOKEN="your-token"
npx @raworc/mcp-server

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

• Documentation: Raworc API Documentation
• RemoteAgent REST (v0): ra-hyp-1 endpoints and examples
• Production Guide: Deploy and operate in production
• Issues: GitHub Issues
• Discussions: GitHub Discussions

📝 Changelog

v0.2.0

• Complete API Coverage: Added all Raworc REST API endpoints
• Service Account Management: Full CRUD operations for service accounts
• Role-Based Access Control: Complete RBAC implementation with roles and role bindings
• Enhanced Session Management: Added session forking, state management, and message operations
• Advanced Agent Operations: Full agent lifecycle management with deployment and monitoring
• Comprehensive Secret Management: Enhanced secret operations with proper access controls
• Build Management: Space build triggering and monitoring capabilities
• Production Enhancements: Improved error handling, logging, and MCP protocol compliance

v0.1.0

• Initial release
• Basic MCP protocol implementation
• Core Raworc API integration
• Session, space, agent, and secret management
• Health monitoring and version information
• npx installation support
• Production-ready error handling

🔗 Links

• Repository: https://github.com/harshapalnati/raworc-mcpserver
• npm Package: @raworc/mcp-server
• Raworc API: https://raworc.com/docs/api/rest-api