@portel/mcp

MCP (Model Context Protocol) client library for connecting to and interacting with MCP servers. Provides transport abstraction, configuration management, and user elicitation utilities.

Part of the Portel Ecosystem

┌─────────────────────────────────────────────────────────────────┐
│                        @portel/cli                              │
│            CLI utilities: formatting, progress, logging         │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │
┌─────────────────────────────────────────────────────────────────┐
│                  @portel/mcp (this package)                     │
│              MCP protocol: client, transport, config            │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │
┌─────────────────────────────────────────────────────────────────┐
│                     @portel/photon-core                         │
│         Core library: schema extraction, generators, UI         │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
┌───────┴───────┐    ┌───────┴───────┐    ┌───────┴───────┐
│ @portel/photon│    │    lumina     │    │ @portel/ncp   │
│  CLI + BEAM   │    │  REST runtime │    │ MCP orchestr. │
└───────────────┘    └───────────────┘    └───────────────┘

Use this package if: You're building tools that need to connect to MCP servers, call MCP tools, or manage MCP server configurations.

Installation

npm install @portel/mcp

Features

MCP Client

Connect to MCP servers and call tools.

import { MCPClient, SDKMCPClientFactory } from '@portel/mcp';

// Create client factory
const factory = new SDKMCPClientFactory();

// Connect to an MCP server
const client = await factory.create({
  command: 'npx',
  args: ['-y', '@anthropic/weather-mcp'],
});

// List available tools
const tools = await client.listTools();
console.log(tools);

// Call a tool
const result = await client.callTool('get-weather', { city: 'London' });
console.log(result);

// Disconnect when done
await client.disconnect();

MCP Proxy

Create a proxy object that maps tool calls to method calls.

import { createMCPProxy, SDKMCPClientFactory } from '@portel/mcp';

const factory = new SDKMCPClientFactory();
const client = await factory.create(config);

// Create proxy - tool names become methods
const mcp = createMCPProxy(client);

// Call tools as methods
const weather = await mcp.getWeather({ city: 'Tokyo' });
const forecast = await mcp.getForecast({ days: 5 });

Configuration Management

Load and save MCP server configurations (Claude Desktop format).

import {
  loadPhotonMCPConfig,
  savePhotonMCPConfig,
  getMCPServerConfig,
  setMCPServerConfig,
  listMCPServers,
} from '@portel/mcp';

// Load config from ~/.photon/mcp-servers.json
const config = loadPhotonMCPConfig();

// List configured servers
const servers = listMCPServers();
// => ['weather', 'database', 'github']

// Get specific server config
const weatherConfig = getMCPServerConfig('weather');

// Add/update a server
setMCPServerConfig('my-server', {
  command: 'node',
  args: ['./my-server.js'],
  env: { API_KEY: '${MY_API_KEY}' },
});

// Save changes
savePhotonMCPConfig(config);

User Elicitation

Prompt users for input during tool execution.

import { prompt, confirm, elicit, setElicitHandler } from '@portel/mcp';

// Simple prompts
const name = await prompt('What is your name?');
const proceed = await confirm('Continue?');

// Rich elicitation with schema
const result = await elicit({
  message: 'Configure settings',
  schema: {
    type: 'object',
    properties: {
      theme: { type: 'string', enum: ['light', 'dark'] },
      fontSize: { type: 'number', minimum: 8, maximum: 24 },
    },
  },
});

// Custom handler (for different UIs)
setElicitHandler(async (options) => {
  // Custom UI implementation
  return { action: 'submit', data: formData };
});

API Reference

MCP Client

| Export | Description | |--------|-------------| | MCPClient | Core MCP client class | | MCPClientFactory | Factory interface for creating clients | | SDKMCPClientFactory | Factory using @modelcontextprotocol/sdk | | createMCPProxy(client) | Create proxy for tool-as-method calls | | MCPError | Base error class | | MCPNotConnectedError | Client not connected error | | MCPToolError | Tool execution error |

Configuration

| Export | Description | |--------|-------------| | loadPhotonMCPConfig() | Load config from ~/.photon | | savePhotonMCPConfig(config) | Save config to ~/.photon | | getMCPServerConfig(name) | Get server config by name | | setMCPServerConfig(name, config) | Add/update server config | | removeMCPServerConfig(name) | Remove server config | | listMCPServers() | List all configured servers | | isMCPConfigured(name) | Check if server is configured | | resolveEnvVars(config) | Resolve ${VAR} in config |

Elicitation

| Export | Description | |--------|-------------| | prompt(message) | Simple text prompt | | confirm(message) | Yes/no confirmation | | elicit(options) | Rich form elicitation | | setPromptHandler(handler) | Set custom prompt handler | | setElicitHandler(handler) | Set custom elicit handler | | elicitReadline | Readline-based handler | | elicitNativeDialog | Native dialog handler |

Types

interface MCPServerConfig {
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

interface MCPToolInfo {
  name: string;
  description?: string;
  inputSchema?: object;
}

interface MCPToolResult {
  content: Array<{ type: string; text?: string }>;
  isError?: boolean;
}

interface ElicitOptions {
  message: string;
  schema?: object;
  requestedFields?: string[];
}

interface ElicitResult {
  action: 'submit' | 'cancel' | 'skip';
  data?: Record<string, any>;
}

License

MIT