@pencil-agent/nano-pencil 1.1.0 → 1.2.0

package/README.md

@@ -24,6 +24,16 @@ nanopencil
 
 进入后可直接输入需求，模型会使用 read、write、edit、bash 等工具完成任务。
 
+### MCP 支持
+
+NanoPencil 内置支持 MCP (Model Context Protocol)，**默认启用**免费工具（Filesystem、Fetch、Puppeteer、SQLite、Git）。
+
+```bash
+nanopencil  # MCP 默认启用
+```
+
+详见 [MCP 文档](docs/MCP_GUIDE.md) 和 [内置工具列表](docs/BUILTIN_MCP_TOOLS.md)。
+
 ## 常用命令与快捷键
 
 在输入框输入 `/` 可触发命令，例如：

package/core/index.ts

@@ -1,61 +1,87 @@
-/**
- * Core modules shared between all run modes.
- */
-
-export {
-	AgentSession,
-	type AgentSessionConfig,
-	type AgentSessionEvent,
-	type AgentSessionEventListener,
-	type ModelCycleResult,
-	type PromptOptions,
-	type SessionStats,
-} from "./agent-session.js";
-export { type BashExecutorOptions, type BashResult, executeBash, executeBashWithOperations } from "./bash-executor.js";
-export type { CompactionResult } from "./compaction/index.js";
-export { createEventBus, type EventBus, type EventBusController } from "./event-bus.js";
-
-// Extensions system
-export {
-	type AgentEndEvent,
-	type AgentStartEvent,
-	type AgentToolResult,
-	type AgentToolUpdateCallback,
-	type BeforeAgentStartEvent,
-	type ContextEvent,
-	discoverAndLoadExtensions,
-	type ExecOptions,
-	type ExecResult,
-	type Extension,
-	type ExtensionAPI,
-	type ExtensionCommandContext,
-	type ExtensionContext,
-	type ExtensionError,
-	type ExtensionEvent,
-	type ExtensionFactory,
-	type ExtensionFlag,
-	type ExtensionHandler,
-	ExtensionRunner,
-	type ExtensionShortcut,
-	type ExtensionUIContext,
-	type LoadExtensionsResult,
-	type MessageRenderer,
-	type RegisteredCommand,
-	type SessionBeforeCompactEvent,
-	type SessionBeforeForkEvent,
-	type SessionBeforeSwitchEvent,
-	type SessionBeforeTreeEvent,
-	type SessionCompactEvent,
-	type SessionForkEvent,
-	type SessionShutdownEvent,
-	type SessionStartEvent,
-	type SessionSwitchEvent,
-	type SessionTreeEvent,
-	type ToolCallEvent,
-	type ToolDefinition,
-	type ToolRenderResultOptions,
-	type ToolResultEvent,
-	type TurnEndEvent,
-	type TurnStartEvent,
-	wrapToolsWithExtensions,
-} from "./extensions/index.js";
+/**
+ * Core modules shared between all run modes.
+ */
+
+export {
+  AgentSession,
+  type AgentSessionConfig,
+  type AgentSessionEvent,
+  type AgentSessionEventListener,
+  type ModelCycleResult,
+  type PromptOptions,
+  type SessionStats,
+} from "./agent-session.js";
+export {
+  type BashExecutorOptions,
+  type BashResult,
+  executeBash,
+  executeBashWithOperations,
+} from "./bash-executor.js";
+export type { CompactionResult } from "./compaction/index.js";
+export {
+  createEventBus,
+  type EventBus,
+  type EventBusController,
+} from "./event-bus.js";
+
+// Extensions system
+export {
+  type AgentEndEvent,
+  type AgentStartEvent,
+  type AgentToolResult,
+  type AgentToolUpdateCallback,
+  type BeforeAgentStartEvent,
+  type ContextEvent,
+  discoverAndLoadExtensions,
+  type ExecOptions,
+  type ExecResult,
+  type Extension,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+  type ExtensionContext,
+  type ExtensionError,
+  type ExtensionEvent,
+  type ExtensionFactory,
+  type ExtensionFlag,
+  type ExtensionHandler,
+  ExtensionRunner,
+  type ExtensionShortcut,
+  type ExtensionUIContext,
+  type LoadExtensionsResult,
+  type MessageRenderer,
+  type RegisteredCommand,
+  type SessionBeforeCompactEvent,
+  type SessionBeforeForkEvent,
+  type SessionBeforeSwitchEvent,
+  type SessionBeforeTreeEvent,
+  type SessionCompactEvent,
+  type SessionForkEvent,
+  type SessionShutdownEvent,
+  type SessionStartEvent,
+  type SessionSwitchEvent,
+  type SessionTreeEvent,
+  type ToolCallEvent,
+  type ToolDefinition,
+  type ToolRenderResultOptions,
+  type ToolResultEvent,
+  type TurnEndEvent,
+  type TurnStartEvent,
+  wrapToolsWithExtensions,
+} from "./extensions/index.js";
+
+// MCP (Model Context Protocol) support
+export { MCPManager } from "./mcp-manager.js";
+export type {
+  MCPServerConfig,
+  MCPTool,
+  MCPToolResult,
+} from "./mcp/mcp-client.js";
+export {
+  loadMCPConfig,
+  saveMCPConfig,
+  addMCPServer,
+  removeMCPServer,
+  getMCPServer,
+  listMCPServers,
+  listEnabledMCPServers,
+} from "./mcp/mcp-config.js";

package/core/mcp/index.ts

@@ -0,0 +1,23 @@
+/**
+ * MCP (Model Context Protocol) Module
+ *
+ * Exports MCP client and adapter functionality.
+ */
+
+export { MCPClient } from "./mcp-client.js";
+export type { MCPServerConfig, MCPTool, MCPToolResult } from "./mcp-client.js";
+
+export {
+  createMCPTool,
+  getMCPToolDisplayName,
+  loadMCPTools,
+} from "./mcp-adapter.js";
+export {
+  API_KEY_GUIDANCE,
+  formatGuidanceMessage,
+  getAPIKeyGuidance,
+  getMissingKeyServers,
+  getOptionalAPIKeyServers,
+  requiresAPIKey,
+} from "./mcp-guidance.js";
+export type { APIKeyGuidance } from "./mcp-guidance.js";

package/core/mcp/mcp-adapter.ts

@@ -0,0 +1,134 @@
+/**
+ * MCP Tool Adapter
+ *
+ * Adapts MCP tools to work with NanoPencil's tool system.
+ */
+
+import type { ToolDefinition } from "../extensions/index.js";
+import type { MCPClient, MCPTool } from "./mcp-client.js";
+import { formatGuidanceMessage, getAPIKeyGuidance } from "./mcp-guidance.js";
+
+/**
+ * Create a NanoPencil ToolDefinition from an MCP tool definition
+ */
+export function createMCPTool(
+  mcpClient: MCPClient,
+  mcpTool: MCPTool,
+): ToolDefinition {
+  const toolName = mcpTool.name; // Full name like "filesystem/read"
+  const [serverId] = toolName.split("/");
+
+  return {
+    name: toolName,
+    label: toolName,
+    description: mcpTool.description,
+    // Use TypeBox Object schema with any properties since MCP tools have dynamic schemas
+    parameters: {
+      type: "object",
+      properties: {},
+      additionalProperties: true,
+    } as any,
+
+    async execute(
+      toolCallId: string,
+      params: Record<string, any>,
+      signal: AbortSignal | undefined,
+      onUpdate: ((details: any) => void) | undefined,
+      ctx: any,
+    ) {
+      try {
+        const result = await mcpClient.callTool(toolName, params);
+
+        if (result.error) {
+          // Check if error is due to missing API key and provide guidance
+          const guidance = getAPIKeyGuidance(serverId);
+          if (guidance && result.error?.toLowerCase().includes("key")) {
+            return {
+              content: [
+                { type: "text", text: formatGuidanceMessage(guidance, true) },
+              ],
+              details: { error: result.error },
+            };
+          }
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: result.content.map((c) => c.text || "").join("\n"),
+              },
+            ],
+            details: { error: result.error },
+          };
+        }
+
+        // Format tool result for NanoPencil
+        const output = result.content
+          .map((c) => {
+            if (c.type === "text") {
+              return c.text || "";
+            } else if (c.type === "image") {
+              return `[Image: ${c.data?.uri || "unknown"}]`;
+            } else if (c.type === "resource") {
+              return `[Resource: ${JSON.stringify(c.data)}]`;
+            }
+            return "";
+          })
+          .filter(Boolean)
+          .join("\n");
+
+        return {
+          content: [{ type: "text", text: output }],
+          details: undefined,
+        };
+      } catch (error) {
+        // Check if error is related to missing API key and provide guidance
+        const guidance = getAPIKeyGuidance(serverId);
+        if (guidance && String(error).toLowerCase().includes("key")) {
+          return {
+            content: [
+              { type: "text", text: formatGuidanceMessage(guidance, true) },
+            ],
+            details: {
+              error: error instanceof Error ? error.message : String(error),
+            },
+          };
+        }
+
+        return {
+          content: [
+            { type: "text", text: `Failed to call MCP tool ${toolName}` },
+          ],
+          details: {
+            error: error instanceof Error ? error.message : String(error),
+          },
+        };
+      }
+    },
+  };
+}
+
+/**
+ * Load all MCP tools as NanoPencil ToolDefinitions
+ */
+export async function loadMCPTools(
+  mcpClient: MCPClient,
+): Promise<ToolDefinition[]> {
+  const mcpTools = await mcpClient.listTools();
+
+  return mcpTools.map((mcpTool) => createMCPTool(mcpClient, mcpTool));
+}
+
+/**
+ * Get a human-readable display name for an MCP tool
+ */
+export function getMCPToolDisplayName(mcpTool: MCPTool): string {
+  if (mcpTool.displayName) {
+    return mcpTool.displayName;
+  }
+
+  const [serverId, ...nameParts] = mcpTool.name.split("/");
+  const toolName = nameParts.join("/");
+
+  return `${serverId}/${toolName}`;
+}

package/core/mcp/mcp-client.ts

@@ -0,0 +1,296 @@
+/**
+ * MCP (Model Context Protocol) Client
+ *
+ * Provides client functionality to connect to MCP servers and call their tools.
+ * Supports both stdio and SSE transport types.
+ */
+
+import { spawn } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { getAgentDir } from "../../config.js";
+
+export interface MCPServerConfig {
+  /** Unique identifier for this server */
+  id: string;
+  /** Display name */
+  name: string;
+  /** Command to start the server (e.g., "npx", "uvx") */
+  command: string;
+  /** Arguments to pass to the command */
+  args: string[];
+  /** Environment variables to pass */
+  env?: Record<string, string>;
+  /** Transport type: "stdio" or "sse" */
+  transport?: "stdio" | "sse";
+  /** Whether this server is enabled */
+  enabled?: boolean;
+}
+
+export interface MCPTool {
+  /** Tool name (server_id/tool_name format) */
+  name: string;
+  /** Display name */
+  displayName?: string;
+  /** Tool description */
+  description: string;
+  /** JSON Schema for input */
+  inputSchema: any;
+  /** Server ID */
+  serverId: string;
+}
+
+export interface MCPToolResult {
+  /** Tool result content */
+  content: Array<{
+    type: "text" | "image" | "resource";
+    text?: string;
+    data?: any;
+  }>;
+  /** Error message if call failed */
+  error?: string;
+  /** Whether result is partial (hasMore=true) */
+  isPartial?: boolean;
+}
+
+/**
+ * MCP Client class
+ * Manages connections to MCP servers and tool calls
+ */
+export class MCPClient {
+  private servers = new Map<string, MCPServerConfig>();
+  private serverProcesses = new Map<string, any>();
+  private serverTools = new Map<string, MCPTool[]>();
+
+  constructor() {
+    this.loadServersFromConfig();
+  }
+
+  /**
+   * Load MCP server configurations from config file
+   */
+  private loadServersFromConfig(): void {
+    const configDir = getAgentDir();
+    const configPath = join(configDir, "mcp.json");
+
+    if (!existsSync(configPath)) {
+      return;
+    }
+
+    try {
+      const config = JSON.parse(readFileSync(configPath, "utf-8"));
+      const servers: MCPServerConfig[] = config.mcpServers || [];
+
+      for (const server of servers) {
+        if (server.enabled !== false) {
+          this.servers.set(server.id, server);
+        }
+      }
+    } catch (error) {
+      console.error(`Failed to load MCP config: ${error}`);
+    }
+  }
+
+  /**
+   * Get all configured servers
+   */
+  getServers(): MCPServerConfig[] {
+    return Array.from(this.servers.values());
+  }
+
+  /**
+   * Get a specific server by ID
+   */
+  getServer(id: string): MCPServerConfig | undefined {
+    return this.servers.get(id);
+  }
+
+  /**
+   * Add or update a server configuration
+   */
+  addServer(server: MCPServerConfig): void {
+    this.servers.set(server.id, server);
+  }
+
+  /**
+   * Remove a server
+   */
+  removeServer(id: string): void {
+    this.servers.delete(id);
+    this.serverTools.delete(id);
+    this.stopServer(id);
+  }
+
+  /**
+   * Start an MCP server (for stdio transport)
+   */
+  async startServer(serverId: string): Promise<boolean> {
+    const server = this.servers.get(serverId);
+    if (!server) {
+      throw new Error(`Server ${serverId} not found`);
+    }
+
+    if (server.transport === "sse") {
+      // SSE servers don't need to be started as separate processes
+      return true;
+    }
+
+    // Check if already running
+    if (this.serverProcesses.has(serverId)) {
+      return true;
+    }
+
+    try {
+      const serverProcess = spawn(server.command, server.args, {
+        env: { ...process.env, ...server.env },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+
+      this.serverProcesses.set(serverId, serverProcess);
+
+      // TODO: Initialize MCP handshake, list tools
+      // For now, we'll mark it as started
+      return true;
+    } catch (error) {
+      console.error(`Failed to start MCP server ${serverId}:`, error);
+      return false;
+    }
+  }
+
+  /**
+   * Stop an MCP server
+   */
+  stopServer(serverId: string): void {
+    const process = this.serverProcesses.get(serverId);
+    if (process) {
+      process.kill();
+      this.serverProcesses.delete(serverId);
+    }
+  }
+
+  /**
+   * Stop all running servers
+   */
+  stopAllServers(): void {
+    for (const serverId of this.serverProcesses.keys()) {
+      this.stopServer(serverId);
+    }
+  }
+
+  /**
+   * List available tools from all servers
+   */
+  async listTools(serverId?: string): Promise<MCPTool[]> {
+    const tools: MCPTool[] = [];
+
+    if (serverId) {
+      const serverTools = this.serverTools.get(serverId) || [];
+      tools.push(...serverTools);
+    } else {
+      for (const [_id, serverTools] of this.serverTools) {
+        tools.push(...serverTools);
+      }
+    }
+
+    return tools;
+  }
+
+  /**
+   * Call an MCP tool
+   */
+  async callTool(
+    toolName: string,
+    args: Record<string, any>,
+  ): Promise<MCPToolResult> {
+    // Parse tool name: server_id/tool_name
+    const [serverId, ...nameParts] = toolName.split("/");
+    const toolNameOnly = nameParts.join("/");
+
+    const server = this.servers.get(serverId);
+    if (!server) {
+      return {
+        content: [{ type: "text", text: `Server ${serverId} not found` }],
+        error: `Server ${serverId} not found`,
+      };
+    }
+
+    // For SSE transport, make HTTP request
+    if (server.transport === "sse") {
+      return this.callSSETool(server, toolNameOnly, args);
+    }
+
+    // For stdio transport, send JSON-RPC message
+    return this.callStdioTool(server, toolNameOnly, args);
+  }
+
+  /**
+   * Call tool via stdio (JSON-RPC)
+   */
+  private async callStdioTool(
+    server: MCPServerConfig,
+    toolName: string,
+    args: Record<string, any>,
+  ): Promise<MCPToolResult> {
+    const process = this.serverProcesses.get(server.id);
+    if (!process) {
+      return {
+        content: [{ type: "text", text: `Server ${server.id} is not running` }],
+        error: `Server ${server.id} is not running`,
+      };
+    }
+
+    try {
+      // Send JSON-RPC request
+      const request = {
+        jsonrpc: "2.0",
+        id: Date.now(),
+        method: "tools/call",
+        params: {
+          name: toolName,
+          arguments: args,
+        },
+      };
+
+      process.stdin.write(JSON.stringify(request) + "\n");
+
+      // Read response (simplified - in production, use proper message handling)
+      // For now, return a placeholder
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Tool ${toolName} called (TODO: implement response handling)`,
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Failed to call tool: ${error}` }],
+        error: String(error),
+      };
+    }
+  }
+
+  /**
+   * Call tool via SSE (HTTP)
+   */
+  private async callSSETool(
+    server: MCPServerConfig,
+    toolName: string,
+    args: Record<string, any>,
+  ): Promise<MCPToolResult> {
+    // TODO: Implement SSE tool calls
+    return {
+      content: [{ type: "text", text: `SSE tool calls not yet implemented` }],
+      error: "SSE transport not yet supported",
+    };
+  }
+
+  /**
+   * Check if a tool exists
+   */
+  hasTool(toolName: string): boolean {
+    const [serverId] = toolName.split("/");
+    return this.servers.has(serverId);
+  }
+}