mcp-server-quest

Quest protocol MCP server

mcp-server-quest bootstraps and manages the MCP (Model Context Protocol) data layer for Quest-style workflows. Its primary responsibilities are initializing the on-disk quest data repository (Git-backed), loading built-in quest templates, and exposing a set of MCP tools for agent, quest, task, approval, and workflow operations. The package is intended to be run as a server process that other agents and the mcp-client-quest UI interact with.

Architecture

• Data layer
  • A Git-backed quest data directory is used as the primary persistence store. Initialization is handled by initQuestDataRepo(config.questDataDir).
  • Built-in quest templates are seeded via TemplateModel.initBuiltInTemplates().
• Tool surface
  • Exposes 26 MCP “Tool” exports grouped by category: agent, quest, task, approval, workflow.
  • Tools are collected into a single exported allTools array to be consumed by an MCP transport/server.
• Runtime
  • Minimal server entrypoint (src/index.ts) performs data initialization only; the HTTP dashboard is served by mcp-client-quest.
  • The package expects to run as a long-lived process with graceful SIGINT/SIGTERM handling.
• How it fits in AGENTS ecosystem
  • Acts as the server-side data and orchestration layer for Quest workflows. Agents (workers, human approvers, planner/logging agents) interact with this server via the MCP transport (HTTP or other transports) and the exported tools.
  • The mcp-client-quest package provides the dashboard/UI that queries this server for quests, tasks and templates.

Data flow (high-level)

• On startup: initialize Git repo → seed templates.
• Runtime interactions:
  • Agents register/unregister and post heartbeats (agent tools).
  • Clients create/list/query/modify quests (quest tools).
  • Tasks are assigned, updated, split, analyzed, executed, and results submitted/verified (task tools).
  • Approval workflows coordinate human or automated approvals (approval tools).
  • Workflow guidance tools provide higher-level planning or suggestions (workflow tool).

Tools / API

All tools are exported from src/tools/index.ts and aggregated into allTools: Tool[].

Export name	Category	Purpose / Key parameters
questRegisterAgentTool	agent	Registers a new agent. Key params: agentId, metadata (capabilities, version).
questUnregisterAgentTool	agent	Unregisters an agent. Key params: agentId.
questListAgentsTool	agent	Lists registered agents and metadata. Key params: filter (optional).
questAgentHeartbeatTool	agent	Agent heartbeat to mark liveness. Key params: agentId, timestamp, status.
questCreateQuestTool	quest	Create a new quest. Key params: quest payload (title, description, tasks, metadata).
questQueryQuestTool	quest	Query a quest by id. Key params: questId, projection options.
questListQuestTool	quest	List quests (with filters/pagination). Key params: filters (status, owner, tags).
questArchiveQuestTool	quest	Archive a quest. Key params: questId.
questDeleteQuestTool	quest	Delete a quest. Key params: questId.
questUpdateQuestTool	quest	Update quest metadata or content. Key params: questId, patch/updates.
questAssignTaskTool	task	Assign a task to an agent. Key params: taskId, agentId, assignment metadata.
questQueryTaskTool	task	Query a task by id. Key params: taskId.
questUpdateTaskTool	task	Update task state/metadata. Key params: taskId, updates (status, assignee).
questDeleteTaskTool	task	Delete a task. Key params: taskId.
questSubmitTaskResultTool	task	Submit execution result for a task. Key params: taskId, result payload, validations.
questVerifyTaskTool	task	Verify submitted task results (QA/automated checks). Key params: taskId, verification metadata.
questLogImplementationTool	task	Log implementation details or artifacts for a task. Key params: taskId, log/implementation blob.
questSplitTaskTool	task	Split a task into subtasks. Key params: taskId, split instructions.
questPlanTaskTool	task	Produce a plan for a task (planner assistance). Key params: taskId, context.
questAnalyzeTaskTool	task	Analyze a task (e.g., cost/effort/risks). Key params: taskId, context.
questReflectTaskTool	task	Reflection step to adjust task definitions or lessons learned. Key params: taskId, findings.
questRequestQuestApprovalTool	approval	Request approval for a quest (human or automated). Key params: questId, approvers, reason.
questSubmitApprovalTool	approval	Submit an approval decision. Key params: approvalId, approverId, decision, notes.
questQueryApprovalTool	approval	Query approval status/history. Key params: approvalId, questId.
questRequestTaskApprovalTool	approval	Request approval for a task result. Key params: taskId, approvers, reason.
questWorkflowGuideTool	workflow	Provide guidance for workflows (high-level suggestions or next steps). Key params: questId, context

Notes:

• Each tool is exported as a Tool object from @modelcontextprotocol/sdk types and intended to be registered with the MCP transport layer.
• The tools are grouped and re-exported from src/tools/index.ts. See the code examples section to view the aggregation.

Configuration

Known configuration surface from the package sources:

• config.questDataDir
  • Used by initialization routines: initQuestDataRepo(config.questDataDir).
  • This is provided by the package’s utils/config.js module (config is imported in src/index.ts). Ensure your environment or deployment sets the path where quest data will be persisted.

Environment variables (from agent.json deploy stanza)

• MCP_TRANSPORT_TYPE
  • Example: HTTP transport (“http”). Controls the transport adapter used by MCP. Default set in deployment env to “http”.
• MCP_PORT
  • Example: “3100”. Port the MCP transport listens on when HTTP is used.
• NODE_ENV
  • Standard Node environment variable (e.g., “production”).

Secrets / Vault

• The package does not declare a built-in secrets/vault integration in the provided sources. For production use:
  • Store any Git credentials, signing keys, or other sensitive values in your cluster/host secret manager (Kubernetes Secrets, HashiCorp Vault, etc.).
  • Provide secrets to the process in environment variables or mount them into the container filesystem, and read them inside utils/config.js as appropriate.

Configuration file (config.toml)

• No config.toml is present in the provided sources. If your deployment uses a TOML config, ensure it provides at least:
  • questDataDir = “/path/to/quest-data”
  • Optionally: transportType, port (mapped from MCP_TRANSPORT_TYPE / MCP_PORT)

Code Examples

Key code snippets from the package entry points and tool aggregation.

/**
 * MCP Server Quest Tools
 *
 * All tools organized by category:
 * - agent: Agent management (4 tools)
 * - quest: Quest lifecycle (6 tools)
 * - task: Task management (11 tools)
 * - approval: Approval workflow (4 tools)
 * - workflow: Workflow guidance (1 tool)
 *
 * Total: 26 tools
 */

import type { Tool } from '@modelcontextprotocol/sdk/types.js';

// Re-export all category exports
export * from './agent/index.js';
export * from './quest/index.js';
export * from './task/index.js';
export * from './approval/index.js';
export * from './workflow/index.js';

// Import all tools for aggregation
import {
  questRegisterAgentTool,
  questUnregisterAgentTool,
  questListAgentsTool,
  questAgentHeartbeatTool,
} from './agent/index.js';

import {
  questCreateQuestTool,
  questQueryQuestTool,
  questListQuestTool,
  questArchiveQuestTool,
  questDeleteQuestTool,
  questUpdateQuestTool,
} from './quest/index.js';

import {
  questAssignTaskTool,
  questQueryTaskTool,
  questUpdateTaskTool,
  questDeleteTaskTool,
  questSubmitTaskResultTool,
  questVerifyTaskTool,
  questLogImplementationTool,
  questSplitTaskTool,
  questPlanTaskTool,
  questAnalyzeTaskTool,
  questReflectTaskTool,
} from './task/index.js';

import {
  questRequestQuestApprovalTool,
  questSubmitApprovalTool,
  questQueryApprovalTool,
  questRequestTaskApprovalTool,
} from './approval/index.js';

import {
  questWorkflowGuideTool,
} from './workflow/index.js';

/**
 * All MCP tools organized by category
 */
export const allTools: Tool[] = [
  // Agent tools (4)
  questRegisterAgentTool,
  questUnregisterAgentTool,
  questListAgentsTool,
  questAgentHeartbeatTool,

  // Quest tools (6)
  questCreateQuestTool,
  questQueryQuestTool,
  questListQuestTool,
  questArchiveQuestTool,
  questDeleteQuestTool,

/**
 * MCP Server Quest - Main Entry Point
 * Initializes data directory and quest templates.
 *
 * The dashboard UI is now served by the separate mcp-client-quest package.
 * This entry point only bootstraps the data layer (Git repo + templates).
 */

import { initQuestDataRepo } from './utils/git.js';
import { TemplateModel } from './models/templateModel.js';
import { config } from './utils/config.js';

/**
 * Main server initialization
 */
async function main() {
  console.error('[Startup] Initializing mcp-server-quest...');
  console.error(`[Startup] Quest data directory: ${config.questDataDir}`);

  try {
    // Initialize quest data repository with Git
    console.error('[Startup] Initializing Git repository...');
    await initQuestDataRepo(config.questDataDir);

    // Initialize built-in quest templates
    console.error('[Startup] Initializing quest templates...');
    await TemplateModel.initBuiltInTemplates();

    console.error('[Startup] ✅ Data layer ready!');
  } catch (error) {
    console.error('[Startup] ❌ Failed to initialize:', error);
    process.exit(1);
  }
}

// Handle graceful shutdown
process.on('SIGINT', () => {
  console.error('\n[Shutdown] Received SIGINT, shutting down...');
  process.exit(0);
});

process.on('SIGTERM', () => {
  console.error('\n[Shutdown] Received SIGTERM, shutting down...');
  process.exit(0);
});

// Start initialization
main().catch((error) => {
  console.error('[Startup] Unhandled error:', error);
  process.exit(1);
});

Usage patterns

• Register the exported allTools[] with your MCP transport/server adapter so other agents can call the tools by name.
• Ensure config.questDataDir is writable by the process and backed up if needed.
• Use questRegisterAgentTool on agent startup, and periodically call questAgentHeartbeatTool to indicate liveness.
• Use questCreateQuestTool and related quest/task tools to manage lifecycle; approvals are coordinated via the approval tools.

Dependencies

Direct runtime dependencies (from package metadata):

• @modelcontextprotocol/sdk (Tool types and MCP SDK integration)
• express (v5.2.1) — present in dependencies; used if an HTTP transport or server is implemented

Dev dependencies:

• @types/express, @types/node, typescript, vitest, tsx, coverage tooling.

What depends on mcp-server-quest

• mcp-client-quest (mentioned in the entrypoint comments) — client/UI that queries this package for quests and tasks.
• Other AGENTS platform components that need a Quest MCP server (agents, schedulers, dashboards) will interact with this package via MCP tools/transport.

Agents & Abilities

• Agents in this ecosystem:
  • Worker agents: Receive task assignments via questAssignTaskTool, submit results via questSubmitTaskResultTool, and call questAgentHeartbeatTool.
  • Planner/Analyzer agents: Use questPlanTaskTool and questAnalyzeTaskTool to propose plans or analyze tasks.
  • Implementer agents: Log implementation artifacts with questLogImplementationTool and can request task splits (questSplitTaskTool).
  • Approver agents / human approvers: Interact via questRequestQuestApprovalTool, questRequestTaskApprovalTool and submit decisions with questSubmitApprovalTool.
• Abilities exposed:
  • Each ability is exposed as a Tool export (see Tools / API table). Consumers call these Tool endpoints via the MCP transport. The Tool object includes the name, input/output schema, and handler (per @modelcontextprotocol/sdk conventions).

If you need more detail about any specific tool implementation (handler signatures, input schemas, or utils/config.js contents), point me to the corresponding source file and I will extract precise signatures and examples.