tpmjs/docs/MCP-BRIDGE-STATUS.md

MCP Bridge Implementation Status

Last Updated: 2026-01-12

Overview

The MCP Bridge system allows users to connect local MCP servers (like Chrome DevTools, file systems, or custom tools) to their TPMJS collections. Tools running on the user's machine can be accessed remotely through TPMJS.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        User's Machine                            │
│  ┌─────────────┐     ┌─────────────────────────────────────┐    │
│  │ MCP Server  │────▶│         @tpmjs/bridge CLI           │    │
│  │ (stdio)     │     │  - Connects to local MCP servers    │    │
│  └─────────────┘     │  - Polls TPMJS for tool calls       │    │
│  ┌─────────────┐     │  - Executes tools locally           │    │
│  │ MCP Server  │────▶│  - Returns results to TPMJS         │    │
│  │ (stdio)     │     └──────────────┬──────────────────────┘    │
│  └─────────────┘                    │                            │
└─────────────────────────────────────┼────────────────────────────┘
                                      │ HTTP Polling
                                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                         TPMJS Cloud                              │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐  │
│  │  /api/bridge    │    │  MCP Handlers   │    │  Database   │  │
│  │  - Registration │◀──▶│  - tools/list   │◀──▶│  - Bridge   │  │
│  │  - Tool calls   │    │  - tools/call   │    │    Connection│  │
│  │  - Results      │    │                 │    │  - Bridge   │  │
│  └─────────────────┘    └─────────────────┘    │    Tools    │  │
│                                                 └─────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Packages Created

1. @tpmjs/mcp-client (packages/mcp-client)

MCP client library for connecting to MCP servers.

Features:

• Connect to MCP servers via stdio transport
• Discover tools from servers
• Execute tool calls
• Manage multiple server connections

Usage:

import { MCPClientManager } from '@tpmjs/mcp-client';

const manager = new MCPClientManager();
const tools = await manager.connect({
  id: 'my-server',
  name: 'My MCP Server',
  transport: 'stdio',
  command: 'node',
  args: ['./server.js']
});

const result = await manager.callTool('my-server', 'toolName', { arg: 'value' });
await manager.disconnectAll();

2. @tpmjs/bridge (packages/bridge)

CLI for users to run on their local machine.

Commands:

tpmjs-bridge init              # Create config file
tpmjs-bridge login             # Authenticate with TPMJS
tpmjs-bridge logout            # Remove credentials
tpmjs-bridge add <name>        # Add an MCP server
tpmjs-bridge remove <name>     # Remove an MCP server
tpmjs-bridge list              # List configured servers
tpmjs-bridge config            # Show config path
tpmjs-bridge start             # Start the bridge
tpmjs-bridge status            # Show bridge status

Config file: ~/.tpmjs/bridge.json

{
  "servers": [
    {
      "id": "chrome-devtools",
      "name": "Chrome DevTools",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/claude-in-chrome"]
    }
  ]
}

3. @tpmjs/test-file-writer (packages/tools/test-file-writer)

Test MCP server for development and testing.

Tools:

• write_file - Write content to a file
• read_file - Read content from a file
• list_files - List all files
• delete_file - Delete a file
• get_info - Get server info

Files stored in: ~/.tpmjs/test-files/

Database Schema

BridgeConnection

Tracks active bridge connections per user.

model BridgeConnection {
  id            String    @id @default(cuid())
  userId        String    @unique @map("user_id")
  user          User      @relation(...)
  status        String    @default("disconnected") // 'connected' | 'disconnected'
  socketId      String?   // Internal routing identifier
  tools         Json      @default("[]") // Cached tool definitions
  lastSeen      DateTime?
  clientVersion String?
  clientOS      String?
}

CollectionBridgeTool

Links bridge tools to collections.

model CollectionBridgeTool {
  id           String     @id @default(cuid())
  collectionId String
  collection   Collection @relation(...)
  serverId     String     // e.g., "chrome-devtools"
  toolName     String     // e.g., "screenshot"
  displayName  String?    // Custom display name
  note         String?    // User notes
}

API Endpoints

Bridge Communication API

POST /api/bridge - Bridge registration and tool results

// Register bridge
{ type: 'register', tools: [...], clientVersion: '0.1.0', clientOS: 'darwin' }

// Submit tool result
{ type: 'result', callId: 'xxx', result: {...} }

// Submit tool error
{ type: 'result', callId: 'xxx', error: { message: '...' } }

// Heartbeat
{ type: 'heartbeat' }

GET /api/bridge - Poll for pending tool calls

// Response
{ calls: [{ callId: 'xxx', serverId: 'chrome', toolName: 'screenshot', args: {} }] }

DELETE /api/bridge - Disconnect bridge

User Bridge Status API

GET /api/user/bridge - Get bridge status for current user

{
  status: 'connected' | 'disconnected' | 'stale' | 'never_connected',
  lastSeen: '2026-01-12T...',
  clientVersion: '0.1.0',
  clientOS: 'darwin',
  toolCount: 5,
  servers: [{ id: 'chrome', name: 'Chrome', toolCount: 3, tools: [...] }]
}

Collection Bridge Tools API

GET /api/collections/[id]/bridge-tools - List bridge tools in collection POST /api/collections/[id]/bridge-tools - Add bridge tool to collection PATCH /api/collections/[id]/bridge-tools/[id] - Update bridge tool DELETE /api/collections/[id]/bridge-tools/[id] - Remove bridge tool

MCP Handler Integration

Bridge tools are included in MCP tools/list responses when:

1. The collection has bridge tools added
2. The collection owner has an active bridge connection
3. The bridge status is "connected"

Bridge tool names use the format: bridge--{serverId}--{toolName}

Example: bridge--chrome-devtools--screenshot

UI

Bridge Settings Page

Location: /dashboard/settings/bridge

Features:

• Shows connection status (connected/disconnected/stale/never_connected)
• Lists connected MCP servers and their tools
• Shows last seen time, client version, platform
• Quick start instructions for new users

Navigation

Bridge link added to dashboard sidebar under "Bridge" with link icon.

Testing Results

All components tested successfully:

Component	Status	Notes
MCPClientManager	✅ Pass	Connects, discovers tools, executes calls
Test File Writer	✅ Pass	All 5 tools work correctly
Bridge CLI	✅ Pass	All commands work
Bridge Class	✅ Pass	Connects to servers, registers, polls
API Endpoints	✅ Pass	Auth validation works
Type Check	✅ Pass	No type errors
Lint	✅ Pass	Only pre-existing warnings

What's Working

1. Local MCP Server Connection - Bridge connects to local MCP servers via stdio
2. Tool Discovery - Automatically discovers tools from connected servers
3. Tool Execution - Can execute tools and return results
4. HTTP Polling - Vercel-compatible polling instead of WebSocket
5. Bridge CLI - Full CLI with init, login, add, remove, start commands
6. API Endpoints - All endpoints implemented with proper auth
7. Database Schema - Bridge connections and collection tools stored
8. MCP Integration - Bridge tools included in MCP tools/list
9. UI - Bridge status page with connection info

What Needs Manual Testing

1. End-to-End Flow - Requires logging in via web UI and getting a session token
2. Real MCP Servers - Test with Chrome DevTools, filesystem, etc.
3. Tool Execution via MCP - Call bridge tools through the MCP protocol
4. Collection Integration - Add bridge tools to collections via UI

How to Test Locally

# 1. Build packages
pnpm --filter=@tpmjs/mcp-client build
pnpm --filter=@tpmjs/bridge build
pnpm --filter=@tpmjs/test-file-writer build

# 2. Initialize bridge config
node packages/bridge/dist/cli.js init

# 3. Add test server
node packages/bridge/dist/cli.js add test-file-writer \
  --command "node" \
  --args "$(pwd)/packages/tools/test-file-writer/dist/server.js"

# 4. Start dev server
pnpm --filter=@tpmjs/web dev

# 5. Log in via browser, get session token

# 6. Start bridge (with real token)
node packages/bridge/dist/cli.js start --token <session-token>

# 7. Visit /dashboard/settings/bridge to see status

Future Improvements

• Proper API key authentication (not session tokens)
• Redis for tool call queuing (production)
• WebSocket support for lower latency
• Bridge tool UI in collection editor
• Tool call logging and debugging
• Rate limiting for bridge connections
• Multiple bridge instances per user
• Bridge health monitoring alerts

Files Changed/Created

New Packages

• packages/mcp-client/ - MCP client library
• packages/bridge/ - Bridge CLI
• packages/tools/test-file-writer/ - Test MCP server

Database

• packages/db/prisma/schema.prisma - Added BridgeConnection, CollectionBridgeTool

API Routes

• apps/web/src/app/api/bridge/route.ts - Bridge API
• apps/web/src/app/api/user/bridge/route.ts - User bridge status
• apps/web/src/app/api/collections/[id]/bridge-tools/route.ts - Collection bridge tools
• apps/web/src/app/api/collections/[id]/bridge-tools/[bridgeToolId]/route.ts - Single bridge tool

MCP Integration

• apps/web/src/lib/mcp/handlers.ts - Updated to include bridge tools
• apps/web/src/lib/mcp/tool-converter.ts - Added bridge tool conversion
• apps/web/src/lib/mcp/index.ts - Updated exports

UI

• apps/web/src/app/dashboard/settings/bridge/page.tsx - Bridge status page
• apps/web/src/components/dashboard/DashboardLayout.tsx - Added Bridge nav link

Types

• packages/types/src/collection.ts - Added bridge tool schemas