@vibe-forge/mcp 0.8.0

package/AGENTS.md

@@ -0,0 +1,39 @@
+# MCP 包说明
+
+`@vibe-forge/mcp` 提供独立的 MCP stdio server，以及 `vf-mcp` / `vibe-forge-mcp` 二进制入口。
+
+## 什么时候先看这里
+
+- `vf-mcp` 启动失败
+- MCP tool 注册、过滤、分类行为异常
+- `StartTasks` / `ListTasks` / `AskUserQuestion` 行为异常
+- 想确认独立 MCP CLI 与 core / server 的依赖边界
+
+## 入口
+
+- `cli.js`
+  - 独立 CLI 壳，补齐工作区环境并转交给共享 loader
+- `src/cli.ts`
+  - standalone `vf-mcp` commander 入口
+- `src/command.ts`
+  - MCP options / stdio server 启动逻辑
+- `src/tools/*`
+  - MCP tool 注册与实现
+- `src/tools/task/manager.ts`
+  - MCP task tools 的运行时主逻辑
+  - 直接引用 `@vibe-forge/task`、`@vibe-forge/hooks`、`@vibe-forge/config` 和 `src/sync.ts`
+- `src/sync.ts`
+  - 与 Vibe Forge server 的 session 同步 HTTP API
+
+## 边界约定
+
+- CLI loader 统一走 `@vibe-forge/cli-helper/loader`
+- `@vibe-forge/mcp` 直接引用本包内需要的 task / hook / prompt / sync 模块，不再通过额外 bindings 装配层传递上下文
+- `task` 类工具默认启用
+- MCP tool 实现集中在本包
+
+## 相关文档
+
+- [架构说明](/Users/bytedance/projects/vibe-forge.ai/.ai/rules/docs/ARCHITECTURE.md)
+- [使用文档](/Users/bytedance/projects/vibe-forge.ai/.ai/rules/docs/USAGE.md)
+- [CLI 维护说明](/Users/bytedance/projects/vibe-forge.ai/apps/cli/src/AGENTS.md)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Vibe-Forge.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/__tests__/mcp-test-utils.ts

@@ -0,0 +1,82 @@
+import type { Register } from '#~/tools/types.js'
+import type { z } from 'zod'
+
+type ToolHandler = (args: any) => Promise<any>
+type RegisterServer = Parameters<Register>[0]
+interface RegisterToolOptions {
+  inputSchema?: z.ZodTypeAny
+  title: string
+  description?: string
+}
+type RegisterToolHandler = (args: any) => Promise<any>
+
+interface ToolEntry {
+  handler: ToolHandler
+  schema: z.ZodType<any>
+  title: string
+  description?: string
+}
+
+/**
+ * Creates a tool tester that can register and call tools, simulating the MCP server environment.
+ */
+export function createToolTester() {
+  const tools = new Map<string, ToolEntry>()
+
+  const mockRegister = {
+    registerTool: (name: string, options: RegisterToolOptions, handler: RegisterToolHandler) => {
+      tools.set(name, {
+        // @ts-ignore - The handler type from the SDK is complex with extra context
+        handler: handler as ToolHandler,
+        schema: options.inputSchema as z.ZodType<any>,
+        title: options.title,
+        description: options.description
+      })
+      return {
+        disable: () => {
+          // In a real server this would disable the tool
+        }
+      } as any
+    },
+    registerPrompt: () => {
+      return {
+        disable: () => {}
+      } as any
+    },
+    registerResource: () => {
+      return {
+        disable: () => {}
+      } as any
+    }
+  } as RegisterServer
+
+  return {
+    mockRegister,
+    /**
+     * Calls a registered tool with the given arguments.
+     * Performs Zod validation before calling the handler.
+     */
+    async callTool(name: string, args: unknown) {
+      const tool = tools.get(name)
+      if (!tool) {
+        throw new Error(`Tool "${name}" not found. Registered tools: ${Array.from(tools.keys()).join(', ')}`)
+      }
+
+      // Simulate Zod validation that McpServer would do
+      const validatedArgs = tool.schema.parse(args)
+      return tool.handler(validatedArgs)
+    },
+    /**
+     * Gets information about a registered tool.
+     */
+    getToolInfo(name: string) {
+      return tools.get(name)
+    },
+    /**
+     * Returns a list of all registered tool names.
+     */
+    getRegisteredTools() {
+      return Array.from(tools.keys())
+    }
+  }
+}

package/__tests__/proxy.spec.ts

@@ -0,0 +1,68 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { describe, expect, it, vi } from 'vitest'
+
+import { createFilteredRegister, shouldEnableCategory } from '#~/tools/proxy.js'
+
+describe('proxy logic', () => {
+  describe('shouldEnableCategory', () => {
+    it('should enable when no filters', () => {
+      expect(shouldEnableCategory('cat1', {})).toBe(true)
+    })
+
+    it('should respect include', () => {
+      expect(shouldEnableCategory('cat1', { include: ['cat1'] })).toBe(true)
+      expect(shouldEnableCategory('cat2', { include: ['cat1'] })).toBe(false)
+    })
+
+    it('should respect exclude', () => {
+      expect(shouldEnableCategory('cat1', { exclude: ['cat1'] })).toBe(false)
+      expect(shouldEnableCategory('cat2', { exclude: ['cat1'] })).toBe(true)
+    })
+
+    it('should prioritize include then exclude', () => {
+      expect(shouldEnableCategory('cat1', { include: ['cat1'], exclude: ['cat1'] })).toBe(false)
+      expect(shouldEnableCategory('cat1', { include: ['cat1'], exclude: ['cat2'] })).toBe(true)
+    })
+  })
+
+  describe('createFilteredRegister', () => {
+    const mockTool = { disable: vi.fn() }
+    const mockPrompt = { disable: vi.fn() }
+    const mockResource = { disable: vi.fn() }
+
+    const mockServer = {
+      registerTool: vi.fn().mockReturnValue(mockTool),
+      registerPrompt: vi.fn().mockReturnValue(mockPrompt),
+      registerResource: vi.fn().mockReturnValue(mockResource)
+    } as unknown as McpServer
+
+    it('should disable tool if not included', () => {
+      const proxy = createFilteredRegister(mockServer, {
+        tools: { include: ['tool1'] }
+      })
+
+      proxy.registerTool('tool2', { description: 'test' }, async () => ({ content: [] }))
+      expect(mockTool.disable).toHaveBeenCalled()
+    })
+
+    it('should NOT disable tool if included', () => {
+      const proxy = createFilteredRegister(mockServer, {
+        tools: { include: ['tool1'] }
+      })
+
+      vi.clearAllMocks()
+      proxy.registerTool('tool1', { description: 'test' }, async () => ({ content: [] }))
+      expect(mockTool.disable).not.toHaveBeenCalled()
+    })
+
+    it('should disable tool if excluded', () => {
+      const proxy = createFilteredRegister(mockServer, {
+        tools: { exclude: ['tool1'] }
+      })
+
+      vi.clearAllMocks()
+      proxy.registerTool('tool1', { description: 'test' }, async () => ({ content: [] }))
+      expect(mockTool.disable).toHaveBeenCalled()
+    })
+  })
+})

package/__tests__/task-manager.spec.ts

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  run: vi.fn(),
+  generateAdapterQueryOptions: vi.fn(),
+  callHook: vi.fn(),
+  loadInjectDefaultSystemPromptValue: vi.fn(),
+  mergeSystemPrompts: vi.fn(),
+  extractTextFromMessage: vi.fn(),
+  postSessionEvent: vi.fn(),
+  fetchSessionMessages: vi.fn()
+}))
+
+vi.mock('@vibe-forge/task', () => ({
+  run: mocks.run,
+  generateAdapterQueryOptions: mocks.generateAdapterQueryOptions
+}))
+
+vi.mock('@vibe-forge/hooks', () => ({
+  callHook: mocks.callHook
+}))
+
+vi.mock('@vibe-forge/config', () => ({
+  loadInjectDefaultSystemPromptValue: mocks.loadInjectDefaultSystemPromptValue,
+  mergeSystemPrompts: mocks.mergeSystemPrompts
+}))
+
+vi.mock('@vibe-forge/utils/chat-message', () => ({
+  extractTextFromMessage: mocks.extractTextFromMessage
+}))
+
+vi.mock('#~/sync.js', () => ({
+  postSessionEvent: mocks.postSessionEvent,
+  fetchSessionMessages: mocks.fetchSessionMessages
+}))
+
+describe('taskManager fatal error scenarios', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.generateAdapterQueryOptions.mockResolvedValue([
+      {},
+      {
+        systemPrompt: undefined,
+        tools: undefined,
+        skills: undefined,
+        mcpServers: undefined
+      }
+    ])
+    mocks.callHook.mockResolvedValue(undefined)
+    mocks.loadInjectDefaultSystemPromptValue.mockResolvedValue(true)
+    mocks.mergeSystemPrompts.mockReturnValue(undefined)
+    mocks.postSessionEvent.mockResolvedValue(undefined)
+    mocks.fetchSessionMessages.mockResolvedValue([])
+    mocks.extractTextFromMessage.mockReturnValue('')
+  })
+
+  it('keeps the task failed when a fatal error is followed by stop', async () => {
+    const { TaskManager } = await import('#~/tools/task/manager.js')
+
+    mocks.run.mockImplementationOnce(async (_options: unknown, adapterOptions: any) => {
+      const session = {
+        emit: vi.fn(() => {
+          adapterOptions.onEvent({
+            type: 'error',
+            data: {
+              message: 'Incomplete response returned',
+              fatal: true
+            }
+          })
+          adapterOptions.onEvent({
+            type: 'stop',
+            data: undefined
+          })
+        }),
+        kill: vi.fn()
+      }
+      return { session }
+    })
+
+    const managedTaskManager = new TaskManager()
+    await managedTaskManager.startTask({
+      taskId: 'task-fatal-stop',
+      description: 'trigger',
+      background: false
+    })
+
+    const task = managedTaskManager.getTask('task-fatal-stop')
+    expect(task?.status).toBe('failed')
+    expect(task?.logs).toContain('Incomplete response returned')
+  })
+})

package/__tests__/tools.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+
+import { createMcpTools } from '#~/tools/index.js'
+import wait from '#~/tools/general/wait.js'
+
+import { createToolTester } from './mcp-test-utils.js'
+
+describe('mcp tools integration', () => {
+  it('registers task tools by default', () => {
+    expect(createMcpTools()).toHaveProperty('task')
+  })
+
+  describe('wait tool', () => {
+    it('should register wait tool', () => {
+      const tester = createToolTester()
+      wait(tester.mockRegister)
+
+      expect(tester.getRegisteredTools()).toContain('wait')
+      const info = tester.getToolInfo('wait')
+      expect(info?.title).toBe('Wait Tool')
+    })
+
+    it('should wait for specified time', async () => {
+      const tester = createToolTester()
+      wait(tester.mockRegister)
+
+      const start = Date.now()
+      const ms = 100
+      const result = await tester.callTool('wait', { ms }) as any
+      const duration = Date.now() - start
+
+      expect(duration).toBeGreaterThanOrEqual(ms - 10) // Allow some jitter
+      expect(result.content[0].text).toBe(`Finished waiting for ${ms}ms`)
+    })
+
+    it('should fail validation with out-of-range input', async () => {
+      const tester = createToolTester()
+      wait(tester.mockRegister)
+
+      // Max is 60000ms
+      await expect(tester.callTool('wait', { ms: 70000 }))
+        .rejects.toThrow()
+
+      // Min is 0ms
+      await expect(tester.callTool('wait', { ms: -1 }))
+        .rejects.toThrow()
+    })
+  })
+})

package/cli.js

@@ -0,0 +1,3 @@
+require('@vibe-forge/cli-helper/entry').runCliPackageEntrypoint({
+  packageDir: __dirname
+})

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@vibe-forge/mcp",
+  "version": "0.8.0",
+  "description": "Vibe Forge MCP server",
+  "imports": {
+    "#~/*.js": {
+      "__vibe-forge__": {
+        "default": "./src/*.ts"
+      },
+      "default": {
+        "import": "./dist/index.mjs",
+        "require": "./dist/index.js"
+      }
+    }
+  },
+  "exports": {
+    ".": {
+      "__vibe-forge__": {
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "import": "./dist/index.mjs",
+        "require": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "vibe-forge-mcp": "./cli.js",
+    "vf-mcp": "./cli.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "commander": "^12.1.0",
+    "zod": "^3.24.1",
+    "@vibe-forge/cli-helper": "^0.8.0",
+    "@vibe-forge/config": "^0.8.0",
+    "@vibe-forge/register": "^0.8.0",
+    "@vibe-forge/hooks": "^0.8.0",
+    "@vibe-forge/task": "^0.8.0",
+    "@vibe-forge/utils": "^0.8.0",
+    "@vibe-forge/types": "^0.8.0"
+  },
+  "scripts": {
+    "test": "pnpm -C ../.. exec vitest run --workspace vitest.workspace.ts --project bundler packages/mcp/__tests__"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,15 @@
+import { program } from 'commander'
+
+import { configureMcpCommand } from './command'
+import { getMcpDescription, getMcpVersion } from './package-config'
+
+const version = getMcpVersion()
+
+program
+  .name('vf-mcp')
+  .description(getMcpDescription())
+  .version(version)
+
+configureMcpCommand(program, version)
+
+void program.parseAsync()

package/src/command.ts

@@ -0,0 +1,63 @@
+import process from 'node:process'
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import type { Command } from 'commander'
+
+import type { McpOptions } from './types'
+import { createMcpTools } from './tools'
+import { createFilteredRegister, shouldEnableCategory } from './tools/proxy'
+
+export const configureMcpCommand = (command: Command, version: string) => (
+  command
+    .description('Start MCP server (stdio)')
+    .option('--include-tools <tools>', 'Comma-separated list of tools to include')
+    .option('--exclude-tools <tools>', 'Comma-separated list of tools to exclude')
+    .option('--include-prompts <prompts>', 'Comma-separated list of prompts to include')
+    .option('--exclude-prompts <prompts>', 'Comma-separated list of prompts to exclude')
+    .option('--include-resources <resources>', 'Comma-separated list of resources to include')
+    .option('--exclude-resources <resources>', 'Comma-separated list of resources to exclude')
+    .option('--include-category <categories>', 'Comma-separated list of categories to include')
+    .option('--exclude-category <categories>', 'Comma-separated list of categories to exclude')
+    .action(async (opts: McpOptions) => {
+      const parseList = (s?: string) => s?.split(',').map((t) => t.trim()).filter(Boolean) ?? []
+      const tools = createMcpTools()
+
+      const server = new McpServer({
+        name: 'vibe-forge',
+        version
+      })
+
+      const proxyServer = createFilteredRegister(server, {
+        tools: { include: parseList(opts.includeTools), exclude: parseList(opts.excludeTools) },
+        prompts: { include: parseList(opts.includePrompts), exclude: parseList(opts.excludePrompts) },
+        resources: { include: parseList(opts.includeResources), exclude: parseList(opts.excludeResources) }
+      })
+
+      const categoryFilter = {
+        include: parseList(opts.includeCategory),
+        exclude: parseList(opts.excludeCategory)
+      }
+
+      const runType = process.env.__VF_PROJECT_AI_RUN_TYPE__ ?? 'cli'
+
+      Object.entries(tools).forEach(([category, register]) => {
+        if (category === 'interaction' && runType !== 'server') {
+          return
+        }
+
+        if (shouldEnableCategory(category, categoryFilter)) {
+          register(proxyServer)
+        }
+      })
+
+      const transport = new StdioServerTransport()
+      await server.connect(transport)
+
+      console.error('MCP server started on stdio')
+    })
+)
+
+export function registerMcpCommand(program: Command, version: string) {
+  return configureMcpCommand(program.command('mcp'), version)
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { configureMcpCommand, registerMcpCommand } from './command'
+export type {
+  McpManagedTaskInput,
+  McpOptions,
+  McpResolvedTaskQueryOptions,
+  McpSelectionFilter,
+  McpTaskBindings,
+  McpTaskDefinitionType,
+  McpTaskHookInputs,
+  McpTaskOutputEvent,
+  McpTaskQueryOptions,
+  McpTaskRunOptions,
+  McpTaskSession
+} from './types'

package/src/package-config.ts

@@ -0,0 +1,22 @@
+let packageJson: Record<string, unknown> | undefined
+
+const getPackageJson = () => {
+  if (!packageJson) {
+    try {
+      // eslint-disable-next-line ts/no-require-imports
+      packageJson = require('@vibe-forge/mcp/package.json') as Record<string, unknown>
+    } catch {
+      packageJson = {}
+    }
+  }
+  return packageJson
+}
+
+export const getPackageConfig = (key: string, defaultValue = '') => {
+  const value = getPackageJson()[key]
+  return typeof value === 'string' ? value : defaultValue
+}
+
+export const getMcpVersion = () => getPackageConfig('version', '0.0.0')
+
+export const getMcpDescription = () => getPackageConfig('description', 'Vibe Forge MCP')

package/src/sync.ts

@@ -0,0 +1,64 @@
+import process from 'node:process'
+
+import type { WSEvent } from '@vibe-forge/types'
+import { extractTextFromMessage } from '@vibe-forge/utils/chat-message'
+
+const getServerBaseUrl = () => {
+  const host = process.env.__VF_PROJECT_AI_SERVER_HOST__ ?? 'localhost'
+  const port = process.env.__VF_PROJECT_AI_SERVER_PORT__ ?? '8787'
+  return `http://${host}:${port}`
+}
+
+export const getParentSessionId = () => {
+  const ctxId = process.env.__VF_PROJECT_AI_CTX_ID__
+  return ctxId ?? undefined
+}
+
+export const createChildSession = async (params: {
+  id: string
+  title?: string
+  parentSessionId?: string
+}) => {
+  const baseUrl = getServerBaseUrl()
+  const response = await fetch(`${baseUrl}/api/sessions`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      id: params.id,
+      title: params.title,
+      parentSessionId: params.parentSessionId,
+      start: false
+    })
+  })
+  if (!response.ok) {
+    const errorText = await response.text()
+    throw new Error(`Failed to create session: ${response.statusText} - ${errorText}`)
+  }
+  return response.json()
+}
+
+export const postSessionEvent = async (sessionId: string, payload: Record<string, unknown>) => {
+  const baseUrl = getServerBaseUrl()
+  const response = await fetch(`${baseUrl}/api/sessions/${sessionId}/events`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload)
+  })
+  if (!response.ok) {
+    const errorText = await response.text()
+    throw new Error(`Failed to post session event: ${response.statusText} - ${errorText}`)
+  }
+}
+
+export const fetchSessionMessages = async (sessionId: string) => {
+  const baseUrl = getServerBaseUrl()
+  const response = await fetch(`${baseUrl}/api/sessions/${sessionId}/messages`)
+  if (!response.ok) {
+    const errorText = await response.text()
+    throw new Error(`Failed to fetch session messages: ${response.statusText} - ${errorText}`)
+  }
+  const data = await response.json() as { messages: WSEvent[] }
+  return data.messages ?? []
+}
+
+export { extractTextFromMessage }

package/src/tools/general/wait.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+
+import { defineRegister } from '../types'
+
+export default defineRegister(({ registerTool }) => {
+  registerTool(
+    'wait',
+    {
+      title: 'Wait Tool',
+      description: 'Wait for a specified amount of time (milliseconds)',
+      inputSchema: z.object({
+        ms: z.number().min(0).max(60000).describe('Time to wait in milliseconds')
+      })
+    },
+    async ({ ms }) => {
+      await new Promise((resolve) => setTimeout(resolve, ms))
+      return {
+        content: [{ type: 'text', text: `Finished waiting for ${ms}ms` }]
+      }
+    }
+  )
+})

package/src/tools/index.ts

@@ -0,0 +1,14 @@
+import wait from './general/wait'
+import askUser from './interaction/ask-user'
+import type { Register } from './types'
+import { createTaskRegister } from './task'
+
+export const createMcpTools = (): Record<string, Register> => ({
+  general: (server) => {
+    wait(server)
+  },
+  interaction: (server) => {
+    askUser(server)
+  },
+  task: createTaskRegister()
+})

package/src/tools/interaction/ask-user.ts

@@ -0,0 +1,63 @@
+import process from 'node:process'
+import { z } from 'zod'
+import { defineRegister } from '../types'
+
+const Schema = z.object({
+  question: z.string().describe('The question to ask the user'),
+  options: z.array(z.object({
+    label: z.string().describe('The label of the option'),
+    description: z.string().optional().describe('The description of the option')
+  })).optional().describe('The options for the user to select from'),
+  multiselect: z.boolean().optional().describe('Whether the user can select multiple options')
+})
+
+export default defineRegister(({ registerTool }) => {
+  registerTool(
+    'AskUserQuestion',
+    {
+      title: 'Ask User Question',
+      description: 'Ask the user a question via the web interface',
+      inputSchema: Schema
+    },
+    async (args) => {
+      const { question, options, multiselect } = args
+      const sessionId = process.env.__VF_PROJECT_AI_SESSION_ID__
+
+      if (!sessionId) {
+        throw new Error(
+          'Session ID not found in environment variables. This tool can only be used within a Vibe Forge session.'
+        )
+      }
+
+      const host = process.env.__VF_PROJECT_AI_SERVER_HOST__ ?? 'localhost'
+      const port = process.env.__VF_PROJECT_AI_SERVER_PORT__ ?? '8787'
+      const response = await fetch(`http://${host}:${port}/api/interact/ask`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          sessionId,
+          question,
+          options,
+          multiselect
+        })
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        throw new Error(`Failed to ask user question: ${response.statusText} - ${errorText}`)
+      }
+
+      const result = await response.json()
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result.result)
+          }
+        ]
+      }
+    }
+  )
+})

package/src/tools/proxy.ts

@@ -0,0 +1,63 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+
+import type { Register } from './types.js'
+
+export interface FilterOptions {
+  include?: string[]
+  exclude?: string[]
+}
+
+export function createFilteredRegister(
+  server: McpServer,
+  options: {
+    tools?: FilterOptions
+    prompts?: FilterOptions
+    resources?: FilterOptions
+  }
+): Parameters<Register>[0] {
+  const shouldEnable = (name: string, filter?: FilterOptions) => {
+    if (!filter) return true
+    const { include = [], exclude = [] } = filter
+    if (include.length > 0 && !include.includes(name)) return false
+    if (exclude.includes(name)) return false
+    return true
+  }
+
+  return {
+    registerTool: (...args) => {
+      const tool = server.registerTool(...args)
+      const name = args[0]
+      if (!shouldEnable(name, options.tools)) {
+        tool.disable()
+      }
+      return tool
+    },
+    registerPrompt: (...args) => {
+      const prompt = server.registerPrompt(...args)
+      const name = args[0]
+      if (!shouldEnable(name, options.prompts)) {
+        prompt.disable()
+      }
+      return prompt
+    },
+    registerResource: (...args) => {
+      // @ts-ignore - McpServer types have complex overloads that are hard to proxy perfectly
+      const resource = server.registerResource(...args)
+      const name = args[0]
+      if (!shouldEnable(name, options.resources)) {
+        resource.disable()
+      }
+      return resource
+    }
+  }
+}
+
+export const shouldEnableCategory = (
+  category: string,
+  options: FilterOptions
+) => {
+  const { include = [], exclude = [] } = options
+  if (include.length > 0 && !include.includes(category)) return false
+  if (exclude.includes(category)) return false
+  return true
+}

package/src/tools/task/index.ts

@@ -0,0 +1,172 @@
+import process from 'node:process'
+
+import { callHook } from '@vibe-forge/hooks'
+import { uuid } from '@vibe-forge/utils/uuid'
+import { z } from 'zod'
+
+import { createChildSession, getParentSessionId } from '#~/sync.js'
+import type { McpManagedTaskInput } from '../../types'
+import { defineRegister } from '../types'
+import { TaskManager } from './manager'
+
+export const createTaskRegister = () => {
+  const taskManager = new TaskManager()
+
+  return defineRegister((server) => {
+    server.registerTool(
+      'StartTasks',
+      {
+        title: 'Start Tasks',
+        description: 'Start multiple tasks in background or foreground',
+        inputSchema: z.object({
+          tasks: z
+            .array(
+              z.object({
+                description: z
+                  .string()
+                  .describe('The description or prompt for the task'),
+                type: z
+                  .enum([
+                    'default',
+                    'spec',
+                    'entity'
+                  ])
+                  .describe('The type of definition to load (default, spec or entity)'),
+                name: z
+                  .string()
+                  .describe('The name of the spec or entity to load, if type is spec or entity. Otherwise, ignored.')
+                  .optional(),
+                adapter: z
+                  .string()
+                  .describe('The adapter to use for the task (e.g. claude-code)')
+                  .optional(),
+                permissionMode: z
+                  .enum(['default', 'acceptEdits', 'plan', 'dontAsk', 'bypassPermissions'])
+                  .describe('Permission mode for the task')
+                  .optional(),
+                background: z
+                  .boolean()
+                  .describe(
+                    'Whether to run in background (default: true). If false, waits for completion and returns logs.'
+                  )
+                  .optional()
+              })
+            )
+            .describe('List of tasks to start')
+        })
+      },
+      async ({ tasks }) => {
+        const resolvedTasks = tasks.map((task): McpManagedTaskInput & { taskId: string } => ({
+          ...task,
+          taskId: uuid()
+        }))
+        const parentSessionId = getParentSessionId()
+
+        await callHook('StartTasks', {
+          cwd: process.cwd(),
+          sessionId: process.env.__VF_PROJECT_AI_SESSION_ID__!,
+          tasks
+        })
+        const syncResults = parentSessionId
+          ? await Promise.allSettled(resolvedTasks.map(task =>
+            createChildSession({
+              id: task.taskId,
+              title: task.name ?? task.description,
+              parentSessionId
+            })
+          ))
+          : []
+        const results = await Promise.allSettled(resolvedTasks
+          .map((task, idx) =>
+            taskManager.startTask({
+              ...task,
+              enableServerSync: parentSessionId != null && syncResults[idx]?.status === 'fulfilled'
+            })
+          ))
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(results.map((r, idx) => {
+              const { taskId, description } = resolvedTasks[idx]
+              const info = taskManager.getTask(taskId)
+              const { session, onStop, serverSync, createdAt, ...safeInfo } = info ?? {}
+              return {
+                taskId,
+                description,
+                status: info?.status ?? r.status,
+                logs: info?.logs ?? [],
+                ...safeInfo
+              }
+            }))
+          }]
+        }
+      }
+    )
+
+    server.registerTool(
+      'GetTaskInfo',
+      {
+        title: 'Get Task Info',
+        description: 'Get the status and logs of a specific task',
+        inputSchema: z.object({
+          taskId: z.string().describe('The ID of the task to check')
+        })
+      },
+      async ({ taskId }) => {
+        const task = taskManager.getTask(taskId)
+        if (!task) {
+          return {
+            content: [{ type: 'text', text: `Task ${taskId} not found.` }],
+            isError: true
+          }
+        }
+        const { session, onStop, serverSync, createdAt, ...safeTask } = task
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify([safeTask])
+          }]
+        }
+      }
+    )
+
+    server.registerTool(
+      'StopTask',
+      {
+        title: 'Stop Task',
+        description: 'Stop a running task',
+        inputSchema: z.object({
+          taskId: z.string().describe('The ID of the task to stop')
+        })
+      },
+      async ({ taskId }) => {
+        const success = taskManager.stopTask(taskId)
+        return {
+          content: [{
+            type: 'text',
+            text: success ? `Task ${taskId} stopped.` : `Failed to stop task ${taskId} (not found or already stopped).`
+          }]
+        }
+      }
+    )
+
+    server.registerTool(
+      'ListTasks',
+      {
+        title: 'List Tasks',
+        description: 'List all managed tasks',
+        inputSchema: z.object({})
+      },
+      async () => {
+        const tasks = taskManager.getAllTasks()
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(tasks.map(({ session, onStop, serverSync, createdAt, ...task }) => task))
+          }]
+        }
+      }
+    )
+  })
+}

package/src/tools/task/manager.ts

@@ -0,0 +1,303 @@
+import process from 'node:process'
+
+import { loadInjectDefaultSystemPromptValue, mergeSystemPrompts } from '@vibe-forge/config'
+import { callHook } from '@vibe-forge/hooks'
+import { generateAdapterQueryOptions, run } from '@vibe-forge/task'
+import type { ChatMessage, McpTaskOutputEvent, McpTaskSession, SessionPermissionMode } from '@vibe-forge/types'
+import { extractTextFromMessage } from '@vibe-forge/utils/chat-message'
+
+import { fetchSessionMessages, postSessionEvent } from '#~/sync.js'
+
+interface ServerSyncState {
+  sessionId: string
+  lastEventIndex: number
+  lastAssistantMessageId?: string
+  seenMessageIds: Set<string>
+  poller?: NodeJS.Timeout
+}
+
+export interface TaskInfo {
+  taskId: string
+  adapter?: string
+  description: string
+  type?: 'default' | 'spec' | 'entity'
+  name?: string
+  permissionMode?: SessionPermissionMode
+  background?: boolean
+  status: 'running' | 'completed' | 'failed'
+  exitCode?: number
+  logs: string[]
+  session?: McpTaskSession
+  createdAt: number
+  onStop?: () => void
+  serverSync?: ServerSyncState
+}
+
+export class TaskManager {
+  private tasks: Map<string, TaskInfo> = new Map()
+
+  public async startTask(options: {
+    taskId: string
+    description: string
+    type?: 'default' | 'spec' | 'entity'
+    name?: string
+    permissionMode?: 'default' | 'acceptEdits' | 'plan' | 'dontAsk' | 'bypassPermissions'
+    adapter?: string
+    background?: boolean
+    enableServerSync?: boolean
+  }): Promise<{ taskId: string; logs?: string[] }> {
+    const { taskId, adapter, description, type, name, permissionMode, background = true, enableServerSync } = options
+
+    // Initialize Task Info
+    const taskInfo: TaskInfo = {
+      taskId,
+      adapter,
+      description,
+      type,
+      name,
+      permissionMode,
+      background,
+      status: 'running',
+      logs: [],
+      createdAt: Date.now()
+    }
+    if (enableServerSync) {
+      taskInfo.serverSync = {
+        sessionId: taskId,
+        lastEventIndex: 0,
+        seenMessageIds: new Set()
+      }
+    }
+    this.tasks.set(taskId, taskInfo)
+
+    try {
+      // Resolve Config
+      const promptType = type !== 'default' ? type : undefined
+      const promptName = name
+      const promptCWD = process.cwd()
+      const [data, resolvedConfig] = await generateAdapterQueryOptions(
+        promptType,
+        promptName,
+        promptCWD
+      )
+      const env = {
+        ...process.env,
+        __VF_PROJECT_AI_CTX_ID__: process.env.__VF_PROJECT_AI_CTX_ID__ ?? taskId
+      }
+      await callHook('GenerateSystemPrompt', {
+        cwd: promptCWD,
+        sessionId: taskId,
+        type: promptType,
+        name: promptName,
+        data
+      }, env)
+
+      const injectDefaultSystemPrompt = await loadInjectDefaultSystemPromptValue(promptCWD)
+
+      // Start Task
+      const ctxId = process.env.__VF_PROJECT_AI_CTX_ID__ ?? taskId
+      const { session } = await run({
+        adapter,
+        cwd: process.cwd(),
+        env: {
+          ...process.env,
+          __VF_PROJECT_AI_CTX_ID__: ctxId
+        }
+      }, {
+        type: 'create',
+        runtime: 'mcp',
+        mode: 'stream',
+        sessionId: taskId,
+        systemPrompt: mergeSystemPrompts({
+          generatedSystemPrompt: resolvedConfig.systemPrompt,
+          injectDefaultSystemPrompt
+        }),
+        permissionMode,
+        tools: resolvedConfig.tools,
+        skills: resolvedConfig.skills,
+        mcpServers: resolvedConfig.mcpServers,
+        promptAssetIds: resolvedConfig.promptAssetIds,
+        onEvent: (event: McpTaskOutputEvent) => {
+          this.handleEvent(taskId, event)
+        }
+      })
+      // Store session for control
+      const task = this.tasks.get(taskId)
+      if (task) {
+        task.session = session
+        // Send initial prompt (description)
+        session.emit({
+          type: 'message',
+          content: [{ type: 'text', text: description }]
+        })
+        this.startServerPolling(taskId)
+      }
+
+      if (!background) {
+        // Wait for completion
+        await new Promise<void>((resolve) => {
+          const task = this.tasks.get(taskId)
+          if (!task) {
+            resolve()
+            return
+          }
+          // Check if already finished
+          if (task.status !== 'running') {
+            resolve()
+            return
+          }
+          // Register callback
+          task.onStop = resolve
+        })
+        return { taskId, logs: taskInfo.logs }
+      }
+    } catch (err) {
+      const task = this.tasks.get(taskId)
+      if (task) {
+        task.status = 'failed'
+        task.logs.push(`Failed to start task: ${err instanceof Error ? err.message : String(err)}`)
+        task.onStop?.()
+      }
+      throw err
+    }
+
+    return { taskId }
+  }
+
+  private handleEvent(taskId: string, event: McpTaskOutputEvent) {
+    const task = this.tasks.get(taskId)
+    if (!task) return
+
+    void this.syncEvent(task, event)
+
+    switch (event.type) {
+      case 'message': {
+        const message = event.data as ChatMessage
+        if (message?.id) {
+          task.serverSync?.seenMessageIds.add(message.id)
+        }
+        if (message?.role === 'assistant' && message.id) {
+          if (task.serverSync) {
+            task.serverSync.lastAssistantMessageId = message.id
+          }
+        }
+        const content = event.data.content
+        let text = ''
+        if (typeof content === 'string') {
+          text = content
+        } else if (Array.isArray(content)) {
+          text = content.map(c => c.type === 'text' ? c.text : '').join('')
+        }
+        if (text) {
+          task.logs.push(text)
+        }
+        break
+      }
+      case 'error': {
+        task.logs.push(event.data.message)
+        if (event.data.fatal !== false) {
+          task.status = 'failed'
+          this.stopServerPolling(taskId)
+          task.onStop?.()
+        }
+        break
+      }
+      case 'stop': {
+        if (task.status === 'failed') {
+          this.stopServerPolling(taskId)
+          task.onStop?.()
+          break
+        }
+        task.status = 'completed'
+        this.stopServerPolling(taskId)
+        task.onStop?.()
+        break
+      }
+      case 'exit':
+        task.status = event.data.exitCode === 0 ? 'completed' : 'failed'
+        task.exitCode = event.data.exitCode ?? undefined
+        task.logs.push(`Process exited with code ${event.data.exitCode}`)
+        this.stopServerPolling(taskId)
+        task.onStop?.()
+        break
+    }
+  }
+
+  private startServerPolling(taskId: string) {
+    const task = this.tasks.get(taskId)
+    if (!task?.serverSync) return
+    if (task.serverSync.poller) return
+
+    const poll = async () => {
+      const current = this.tasks.get(taskId)
+      if (!current?.serverSync || !current.session) return
+      try {
+        const events = await fetchSessionMessages(current.serverSync.sessionId)
+        const startIndex = current.serverSync.lastEventIndex
+        const newEvents = events.slice(startIndex)
+        current.serverSync.lastEventIndex = events.length
+
+        for (const ev of newEvents) {
+          if (ev.type !== 'message') continue
+          if (ev.message.role !== 'user') continue
+          if (ev.message.id && current.serverSync.seenMessageIds.has(ev.message.id)) {
+            continue
+          }
+          if (ev.message.id) {
+            current.serverSync.seenMessageIds.add(ev.message.id)
+          }
+          const text = extractTextFromMessage(ev.message).trim()
+          if (text === '') continue
+          current.session.emit({
+            type: 'message',
+            content: [{ type: 'text', text }],
+            parentUuid: current.serverSync.lastAssistantMessageId
+          })
+        }
+      } catch {}
+    }
+
+    task.serverSync.poller = setInterval(() => {
+      void poll()
+    }, 1000)
+    void poll()
+  }
+
+  private stopServerPolling(taskId: string) {
+    const task = this.tasks.get(taskId)
+    if (task?.serverSync?.poller) {
+      clearInterval(task.serverSync.poller)
+      task.serverSync.poller = undefined
+    }
+  }
+
+  private async syncEvent(task: TaskInfo, event: McpTaskOutputEvent) {
+    if (!task.serverSync) return
+    try {
+      await postSessionEvent(task.serverSync.sessionId, event as unknown as Record<string, unknown>)
+    } catch (err) {
+      task.logs.push(`Sync event failed: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  public getTask(taskId: string): TaskInfo | undefined {
+    return this.tasks.get(taskId)
+  }
+
+  public getAllTasks(): TaskInfo[] {
+    return Array.from(this.tasks.values())
+  }
+
+  public stopTask(taskId: string): boolean {
+    const task = this.tasks.get(taskId)
+    if (task && task.session) {
+      task.session.kill()
+      task.logs.push('Task stopped by user')
+      task.status = 'failed' // or 'stopped' if we had that status
+      this.stopServerPolling(taskId)
+      if (task.onStop) task.onStop()
+      return true
+    }
+    return false
+  }
+}

package/src/tools/types.ts

@@ -0,0 +1,13 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+
+export interface Register {
+  (
+    server: {
+      registerTool: McpServer['registerTool']
+      registerResource: McpServer['registerResource']
+      registerPrompt: McpServer['registerPrompt']
+    }
+  ): void
+}
+
+export const defineRegister = (register: Register) => register

package/src/types.ts

@@ -0,0 +1,23 @@
+export type {
+  McpManagedTaskInput,
+  McpResolvedTaskQueryOptions,
+  McpSelectionFilter,
+  McpTaskBindings,
+  McpTaskDefinitionType,
+  McpTaskHookInputs,
+  McpTaskOutputEvent,
+  McpTaskQueryOptions,
+  McpTaskRunOptions,
+  McpTaskSession
+} from '@vibe-forge/types'
+
+export interface McpOptions {
+  includeTools?: string
+  excludeTools?: string
+  includePrompts?: string
+  excludePrompts?: string
+  includeResources?: string
+  excludeResources?: string
+  includeCategory?: string
+  excludeCategory?: string
+}