@grebyn/toolflow-mcp-server/README.md

MCP server for managing other MCP servers - discover, install, organize into bundles, and automate with workflows. Uses StreamableHTTP transport with dual OAuth/API key authentication.

# ToolFlow MCP Server

**MCP server for managing other MCP servers** - discover, install, organize into bundles, and automate with workflows.

[![npm version](https://badge.fury.io/js/@grebyn%2Ftoolflow-mcp-server.svg)](https://badge.fury.io/js/@grebyn%2Ftoolflow-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

🔧 **MCP Server Management**
- Discover and install MCP servers from multiple registries
- Auto-detect and configure MCP clients (Claude Desktop, Cursor, VSCode, etc.)
- Test server configurations before installation

📦 **Bundle System**
- Create collections of MCP servers for specific use cases
- Share bundles within your organization
- One-click installation of multiple servers

🔄 **Workflow Automation**
- Create step-by-step automation workflows
- Combine multiple MCP servers for complex tasks
- Execute workflows with proper error handling

🔐 **OAuth 2.1 Security**
- Secure authentication with JWT tokens
- Multi-client session management
- Token refresh and revocation support

## Quick Start

### Installation

```bash
# Install globally
npm install -g @grebyn/toolflow-mcp-server

# Or use via npx
npx @grebyn/toolflow-mcp-server
```

### MCP Client Configuration

Add to your MCP client configuration:

**Claude Desktop (`claude_desktop_config.json`):**
```json
{
  "mcpServers": {
    "toolflow": {
      "command": "npx",
      "args": ["@grebyn/toolflow-mcp-server"],
      "env": {
        "OAUTH_BASE_URL": "http://localhost:3000"
      }
    }
  }
}
```

**Cursor (`cursor_config.json`):**
```json
{
  "mcpServers": {
    "toolflow": {
      "command": "npx",
      "args": ["@grebyn/toolflow-mcp-server"],
      "env": {
        "OAUTH_BASE_URL": "http://localhost:3000"
      }
    }
  }
}
```

## Environment Variables

Required environment variables:

```bash
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Optional Configuration
SUPABASE_JWT_SECRET=your_jwt_secret
MCP_SERVER_AUDIENCE=mcp-server:toolflow-mcp-server
OAUTH_BASE_URL=http://localhost:3000
PORT=8080

# Development Only
DISABLE_AUTH=true  # Disable authentication (not recommended for production)
```

## Available Tools

The server provides these MCP tools:

### Client Management
- `detect_mcp_clients` - Find installed MCP clients
- `read_client_config` - Read client configurations
- `write_client_config` - Update client configurations

### Server Testing & Installation
- `test_mcp_server` - Test server configurations
- `run_system_command` - Execute system commands

### Bundle Management
- `list_bundles` - Browse available bundles
- `get_bundle_config` - Get bundle installation config
- `create_bundle` - Create new bundles
- `edit_bundle` - Edit existing bundles

### Workflow Management
- `list_workflows` - Browse available workflows
- `perform_workflow` - Execute workflows
- `create_workflow` - Create new workflows
- `edit_workflow` - Edit existing workflows

## Transport Protocol

This MCP server uses **HTTP transport with OAuth 2.1 authentication**:

- **Protocol**: HTTP with JSON-RPC 2.0
- **Authentication**: OAuth 2.1 with JWT tokens
- **Session Management**: Multi-client support with token refresh
- **Security**: Audience binding, PKCE, token rotation

## Authentication Flow

1. **Initial Connection**: MCP client connects to server
2. **OAuth Discovery**: Client discovers OAuth endpoints
3. **Authorization**: User authorizes via web browser
4. **Token Exchange**: Client exchanges code for JWT tokens
5. **API Access**: Client uses JWT for authenticated tool calls
6. **Token Refresh**: Automatic token refresh when needed

## Development

### Local Development

```bash
# Clone repository
git clone https://github.com/toolflow/toolflow-mcp.git
cd toolflow-mcp

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your configuration

# Start development servers
npm run dev          # Next.js web app
npm run start:mcp    # MCP server
```

### Building

```bash
# Build web application
npm run build

# Build MCP server
npm run build:mcp

# Build both
npm run build:all
```

### Testing MCP Server

```bash
# Test with MCP Inspector
npm run inspect:mcp

# Test specific functionality
node dist/server/index.js
```

## Architecture

- **Web App**: Next.js application for user management and dashboard
- **MCP Server**: Express-based server providing MCP tools
- **Database**: Supabase for authentication and data storage
- **Transport**: HTTP with OAuth 2.1 security

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- 🐛 **Issues**: [GitHub Issues](https://github.com/toolflow/toolflow-mcp/issues)
- 📖 **Documentation**: [ToolFlow Docs](https://toolflow.dev)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/toolflow/toolflow-mcp/discussions)