@girardmedia/bootspring 3.3.3 → 3.4.1

package/dist/mcp/index.d.ts

@@ -0,0 +1,618 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ToolDefinition, ResourceDefinition, ToolHandler, ResourceHandler, InvokeToolOptions, InvokeToolResult, MCPToolResult, WorkflowDefinition, CapabilitiesManifest } from '@bootspring/types';
+export { InvocationContext, InvokeToolOptions, InvokeToolResult, ResourceDefinition, ResourceHandler, ToolDefinition, ToolHandler } from '@bootspring/types';
+import { Vitals } from '@bootspring/shared';
+
+/**
+ * Bootspring MCP Server
+ * Model Context Protocol server for AI assistant integration
+ *
+ * @package @bootspring/mcp
+ * @module server
+ */
+
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+interface RegistryExports {
+    TOOLS: ToolDefinition[];
+    RESOURCES: ResourceDefinition[];
+    toolHandlers: Record<string, ToolHandler>;
+    resourceHandlers: Record<string, ResourceHandler>;
+    trackTelemetry: (event: string, payload: Record<string, unknown>) => void;
+}
+interface MCPServerOptions {
+    name?: string;
+    version?: string;
+    registry: RegistryExports;
+    onToolSuccess?: (toolName: string) => void;
+}
+interface BootstrapModule {
+    getRegistry?: () => RegistryExports;
+    main?: () => Promise<void>;
+    default?: {
+        getRegistry?: () => RegistryExports;
+        main?: () => Promise<void>;
+    };
+}
+interface ResolveRuntimeRegistryOptions {
+    basePath?: string;
+    defaultRegistry?: RegistryExports;
+    loadModule?: (specifier: string) => Promise<BootstrapModule>;
+}
+declare function createServer(options: MCPServerOptions): Promise<Server>;
+declare function isRegistryPopulated(registry: RegistryExports): boolean;
+/**
+ * @deprecated Legacy path resolution for pre-monorepo MCP installations.
+ * Will be removed in v5.0. Use getRegistryExports() from @bootspring/mcp/registry instead.
+ */
+declare function getLegacyRegistryCandidatePaths(basePath?: string): string[];
+declare function resolveRuntimeRegistry(options?: ResolveRuntimeRegistryOptions): Promise<RegistryExports | null>;
+declare function startStdioServer(options: MCPServerOptions): Promise<void>;
+declare function validateDependencies(): ValidationResult;
+declare function main(): Promise<void>;
+
+/**
+ * MCP Registry
+ * Central registry for tool/resource definitions and handler wiring
+ *
+ * @package @bootspring/mcp
+ * @module registry
+ */
+
+type CompatibilityRegistry = ReturnType<typeof createRegistryExports>;
+interface LegacyRegistryModule {
+    TOOLS?: ToolDefinition[] | undefined;
+    RESOURCES?: ResourceDefinition[] | undefined;
+    toolHandlers?: Record<string, ToolHandler> | undefined;
+    resourceHandlers?: Record<string, ResourceHandler> | undefined;
+    trackTelemetry?: ((event: string, payload: Record<string, unknown>) => void) | undefined;
+    getRegistry?: (() => CompatibilityRegistry) | undefined;
+    getRegistryExports?: (() => CompatibilityRegistry) | undefined;
+    default?: LegacyRegistryModule | undefined;
+}
+interface CompatibilityRegistryOptions {
+    basePath?: string | undefined;
+    defaultRegistry?: CompatibilityRegistry | undefined;
+    loadModule?: ((candidatePath: string) => LegacyRegistryModule) | undefined;
+}
+/**
+ * Register a tool with the MCP server
+ */
+declare function registerTool(definition: ToolDefinition, handler: ToolHandler): void;
+/**
+ * Register a resource with the MCP server
+ */
+declare function registerResource(definition: ResourceDefinition, handler: ResourceHandler): void;
+/**
+ * Load tools from a directory of tool modules
+ */
+declare function loadToolsFromDirectory(toolsDir: string): void;
+/**
+ * Invoke a tool from within another tool (tool-to-tool calls)
+ */
+declare function invokeTool(toolName: string, args: Record<string, unknown>, options?: InvokeToolOptions): Promise<InvokeToolResult>;
+/**
+ * Track telemetry events
+ */
+declare function trackTelemetry(event: string, payload: Record<string, unknown>): void;
+declare function createRegistryExports(): {
+    TOOLS: ToolDefinition[];
+    RESOURCES: ResourceDefinition[];
+    toolHandlers: Record<string, ToolHandler>;
+    resourceHandlers: Record<string, ResourceHandler>;
+    trackTelemetry: typeof trackTelemetry;
+};
+declare function getCompatibilityRegistryCandidatePaths(basePath?: string): string[];
+declare function resolveCompatibilityRegistry(options?: CompatibilityRegistryOptions): CompatibilityRegistry;
+/**
+ * Clear the result cache
+ */
+declare function clearCache(): void;
+/**
+ * Get all registered tools
+ */
+declare function getTools(): ToolDefinition[];
+/**
+ * Get all registered resources
+ */
+declare function getResources(): ResourceDefinition[];
+/**
+ * Get all tool handlers
+ */
+declare function getToolHandlers(): Record<string, ToolHandler>;
+/**
+ * Get all resource handlers
+ */
+declare function getResourceHandlers(): Record<string, ResourceHandler>;
+/**
+ * Get the full registry export object
+ */
+declare function getRegistryExports(): {
+    TOOLS: ToolDefinition[];
+    RESOURCES: ResourceDefinition[];
+    toolHandlers: Record<string, ToolHandler>;
+    resourceHandlers: Record<string, ResourceHandler>;
+    trackTelemetry: typeof trackTelemetry;
+};
+
+/**
+ * MCP Response Formatter
+ * Creates well-structured, human-friendly tool responses
+ *
+ * @package @bootspring/mcp
+ * @module response-formatter
+ */
+
+interface SuccessOptions {
+    summary?: string;
+    data?: unknown;
+    hints?: string[];
+    meta?: Record<string, unknown>;
+}
+interface ListOptions<T> {
+    title: string;
+    items: T[];
+    formatter?: (item: T, index: number) => string;
+    emptyMessage?: string;
+    hints?: string[];
+}
+interface AgentData {
+    name: string;
+    category?: string;
+    description: string;
+    expertise: string[];
+    systemPrompt?: string;
+}
+interface SkillData {
+    name: string;
+    description: string;
+    tags?: string[];
+}
+interface TodoItem {
+    text: string;
+    status?: string;
+}
+interface QualityGateResults {
+    name?: string;
+    gate?: string;
+    status: 'pass' | 'fail';
+    passed: number;
+    failed: number;
+    skipped?: number;
+    results: Array<{
+        name: string;
+        status: 'pass' | 'fail' | 'skip';
+        message?: string;
+    }>;
+}
+interface ContextValidationResult {
+    valid: boolean;
+    errors?: string[];
+    warnings?: string[];
+    suggestions?: string[];
+}
+interface ProjectContextDisplay {
+    project?: {
+        name?: string;
+        version?: string;
+    };
+    stack?: {
+        framework?: string;
+        language?: string;
+        database?: string;
+    };
+    plugins?: Record<string, unknown>;
+}
+interface OrchestratorStatus {
+    currentPhase?: string;
+    availableAgents?: number;
+    activeWorkflow?: string;
+    activeWorkflowSignalProgress?: {
+        completedSignals: unknown[];
+        totalSignals: number;
+    };
+    recentSuggestions?: Array<{
+        text?: string;
+    } | string>;
+}
+interface PRDData {
+    name: string;
+    stories: Array<{
+        title: string;
+        status: string;
+    }>;
+}
+interface ProgressInfo {
+    completed: number;
+    total: number;
+    percentage: number;
+}
+interface AssistResponseData {
+    confidenceTier?: 'high' | 'medium' | 'low' | 'very_low';
+    understood?: {
+        intent?: string;
+        confidence?: number;
+        description?: string;
+    };
+    primarySuggestion?: {
+        message: string;
+    };
+    clarificationNeeded?: boolean;
+    clarificationQuestion?: string;
+    clarificationOptions?: string[];
+    suggestions?: Array<{
+        message: string;
+    }>;
+    memoryInsight?: {
+        message: string;
+        recommendation: string;
+    };
+    recommendedTool?: {
+        name: string;
+        args: Record<string, unknown>;
+        reason: string;
+    };
+}
+interface MCPToolResultWithMeta extends MCPToolResult {
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Lead any tool response with the signature Bootspring vitals strip — the
+ * glyph-forward one-liner (progress · tools · cost · burn). Returns fenced
+ * markdown so it survives in every MCP host. Use to prefix a response body:
+ *   `${vitalsLine({ surface: 'agent', tools: 142, cost: 0.43 })}\n\n${body}`
+ */
+declare function vitalsLine(vitals: Vitals): string;
+/**
+ * Format a success response
+ */
+declare function success(options: SuccessOptions): MCPToolResultWithMeta;
+/**
+ * Format an error response
+ */
+declare function error(message: string, suggestions?: string[]): MCPToolResult;
+/**
+ * Format a warning response
+ */
+declare function warning(message: string, suggestions?: string[]): MCPToolResult;
+/**
+ * Format a list response
+ */
+declare function list<T>(options: ListOptions<T>): MCPToolResult;
+/**
+ * Format agent details
+ */
+declare function agentDetails(id: string, agent: AgentData): MCPToolResult;
+/**
+ * Format skill details
+ */
+declare function skillDetails(id: string, skill: SkillData, content?: string | null): MCPToolResult;
+/**
+ * Format todo list
+ */
+declare function todoList(pending: TodoItem[], completed: TodoItem[]): MCPToolResult;
+/**
+ * Format quality gate results
+ */
+declare function qualityResults(results: QualityGateResults): MCPToolResult;
+/**
+ * Format context validation results
+ */
+declare function contextValidation(validation: ContextValidationResult): MCPToolResult;
+/**
+ * Format project context summary
+ */
+declare function contextSummary(ctx: ProjectContextDisplay): MCPToolResult;
+/**
+ * Format orchestrator status
+ */
+declare function orchestratorStatus(status: OrchestratorStatus): MCPToolResult;
+/**
+ * Format PRD/loop status
+ */
+declare function loopStatus(prd: PRDData, progress: ProgressInfo): MCPToolResult;
+/**
+ * Generate a progress bar
+ */
+declare function generateProgressBar(percentage: number): string;
+/**
+ * Format assist response
+ */
+declare function assistResponse(response: AssistResponseData): MCPToolResult;
+
+/**
+ * MCP Capabilities
+ * Capability manifest for assistant clients
+ *
+ * @package @bootspring/mcp
+ * @module capabilities
+ */
+
+interface BuildCapabilitiesOptions {
+    tier?: string;
+    entitled?: boolean;
+    mode?: string;
+    [key: string]: unknown;
+}
+interface WorkflowAccessContext {
+    mode: string;
+    tier: string;
+    entitled: boolean;
+    policyProfile: string;
+}
+interface PolicyProfile {
+    id: string;
+    allowExternalSkills: boolean;
+    blockedWorkflows: string[];
+}
+interface FilteredWorkflows {
+    allowed: WorkflowDefinition[];
+    denied: WorkflowDefinition[];
+}
+interface CapabilitiesDeps {
+    resolveWorkflowAccessContext: (options: BuildCapabilitiesOptions) => WorkflowAccessContext;
+    filterAccessibleWorkflows: (workflows: WorkflowDefinition[], options: BuildCapabilitiesOptions) => FilteredWorkflows;
+    getPolicyProfile: (profileId: string, options: BuildCapabilitiesOptions) => PolicyProfile;
+    listWorkflows: () => WorkflowDefinition[];
+}
+/**
+ * Build capabilities manifest
+ */
+declare function buildCapabilities(deps: CapabilitiesDeps, options?: BuildCapabilitiesOptions): CapabilitiesManifest;
+/**
+ * Build a default capabilities manifest for unauthenticated/local mode
+ */
+declare function buildDefaultCapabilities(): CapabilitiesManifest;
+
+/**
+ * MCP Tools — Docs Intelligence
+ * 5 tools for AI-powered documentation generation, updates, drift detection,
+ * quality improvement, and status checking.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare function registerDocsIntelligenceTools(): void;
+declare const DOCS_INTELLIGENCE_TOOLS: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+}[];
+
+/**
+ * MCP Tools — Quality Intelligence
+ * 3 tools for multi-agent quality analysis, history, and trend.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare function registerQualityIntelligenceTools(): void;
+declare const QUALITY_INTELLIGENCE_TOOLS: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+}[];
+
+/**
+ * MCP Tools — Assistant Parity Matrix
+ * 3 tools for assistant detection, listing, and parity checking.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare function registerAssistantParityTools(): void;
+declare const ASSISTANT_PARITY_TOOLS: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+}[];
+
+/**
+ * MCP Tools — RBAC Management
+ * 4 tools for project member management and audit access.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare const RBAC_TOOLS: ToolDefinition[];
+declare function registerRbacTools(): void;
+
+/**
+ * MCP Tools — Metrics & Telemetry
+ * 3 tools for KPIs, telemetry events, and experiment management.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare const METRICS_TOOLS: ToolDefinition[];
+declare function registerMetricsTools(): void;
+
+/**
+ * MCP Tools — Audit Quality Gates
+ * 4 tools for audit scanning, gate evaluation, findings, and regression.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare const AUDIT_TOOLS: ToolDefinition[];
+declare function registerAuditTools(): void;
+
+/**
+ * MCP Tools — Release Engineering
+ * 4 tools for release gates, prepare, history, and rollback.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare const RELEASE_TOOLS: ToolDefinition[];
+declare function registerReleaseTools(): void;
+
+/**
+ * MCP Tools — Context Sync & Document Integrity
+ * 4 tools for document tracking, integrity checks, sync operations, and conflict resolution.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare const SYNC_TOOLS: ToolDefinition[];
+declare function registerSyncTools(): void;
+
+/**
+ * MCP Tools — Documentation Experience & Onboarding
+ * 4 tools for checklists, progress, guides, and onboarding stats.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare const ONBOARDING_TOOLS: ToolDefinition[];
+declare function registerOnboardingTools(): void;
+
+/**
+ * MCP Tools — Marketplace & Partner Integration
+ * 4 tools for browsing integrations, managing installs, webhooks, and stats.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare const MARKETPLACE_TOOLS: ToolDefinition[];
+declare function registerMarketplaceTools(): void;
+
+/**
+ * MCP Tools — Enterprise Compliance & Governance
+ * 4 tools for controls, risks, actions, and compliance stats.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare const COMPLIANCE_TOOLS: ToolDefinition[];
+declare function registerComplianceTools(): void;
+
+/**
+ * MCP Tools — Notification & Event System
+ * 4 tools for events, notifications, subscriptions, and stats.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare const NOTIFICATION_TOOLS: ToolDefinition[];
+declare function registerNotificationTools(): void;
+
+/**
+ * MCP Tools — Observer Intelligence Layer
+ * 10 tools for session metrics, cost tracking, intelligence analysis,
+ * pattern detection, alerts, trends, comparison, and optimization.
+ *
+ * All tools call the server API — no IP in the MCP layer.
+ * @package @bootspring/mcp
+ */
+
+declare const OBSERVER_TOOLS: ToolDefinition[];
+declare function registerObserverTools(): void;
+
+/**
+ * @bootspring/mcp — Autopilot MCP Tools
+ * 4 tools: autopilot-status, autopilot-config, autopilot-suggestions, autopilot-learning
+ * @package @bootspring/mcp
+ */
+
+declare const AUTOPILOT_TOOLS: ToolDefinition[];
+declare function registerAutopilotTools(): void;
+
+/**
+ * @bootspring/mcp — Brain NLU Router MCP Tool
+ * 1 tool: bootspring_brain — natural language router for skills, workflows, agents, pipelines.
+ * @package @bootspring/mcp
+ */
+
+declare const BRAIN_TOOLS: ToolDefinition[];
+declare function registerBrainTools(): void;
+
+/**
+ * @bootspring/mcp — Swarm Intelligence MCP Tools
+ * 3 tools: bootspring_swarm, bootspring_memory, bootspring_plan
+ * @package @bootspring/mcp
+ */
+
+declare const SWARM_TOOLS: ToolDefinition[];
+declare function registerSwarmTools(): void;
+
+/**
+ * Local Sprint Stack artifact helpers.
+ *
+ * @package @bootspring/mcp
+ */
+type SprintEvidenceKind = 'review' | 'qa' | 'security' | 'release' | 'learning';
+interface SprintArtifactResult {
+    kind: string;
+    path: string;
+    action: 'wrote' | 'appended';
+}
+interface SprintArtifactHistoryItem {
+    id: string;
+    kind: 'plan' | 'note';
+    label: string;
+    path: string;
+    updatedAt: string;
+    detail: string;
+}
+interface SprintArtifactDetail {
+    item: SprintArtifactHistoryItem;
+    content: string;
+    format: 'json' | 'markdown' | 'text';
+    size: number;
+    truncated: boolean;
+}
+declare const SPRINT_EVIDENCE_KINDS: SprintEvidenceKind[];
+declare function sprintDir(projectRoot?: string): string;
+declare function ensureSprintDir(projectRoot?: string): string;
+declare function appendSprintEvidenceNote(kind: SprintEvidenceKind, note: string, projectRoot?: string): SprintArtifactResult;
+declare function listSprintArtifacts(projectRoot?: string, limit?: number): SprintArtifactHistoryItem[];
+declare function readSprintArtifactDetail(artifactPath: string, projectRoot?: string, maxBytes?: number): SprintArtifactDetail | null;
+
+declare const SPRINT_TOOLS: ToolDefinition[];
+declare function registerSprintTools(): void;
+
+/**
+ * MCP Tools — Context Search
+ * Token-efficient code search tool that returns compact file:line:excerpt results
+ * instead of full file contents. Supports file glob, symbol, and content search.
+ *
+ * Local executor — no API calls; uses only Node.js built-ins.
+ * @package @bootspring/mcp
+ */
+
+declare const CONTEXT_SEARCH_TOOLS: ToolDefinition[];
+declare const contextSearchToolHandlers: Record<string, ToolHandler>;
+declare function registerContextSearchTools(): void;
+
+/**
+ * MCP Tools — Output Sandbox
+ *
+ * Since PostToolUse hooks cannot modify tool output, these MCP tools
+ * provide token-efficient alternatives to common operations that
+ * would otherwise dump large amounts of text into context.
+ *
+ * Tools:
+ * - bootspring_read_summary: Read a file and return structure + key sections
+ * - bootspring_test_compact: Run tests and return compact results
+ * - bootspring_doc_search: Search project docs with TF-IDF scoring
+ *
+ * @package @bootspring/mcp
+ */
+
+declare const OUTPUT_SANDBOX_TOOLS: ToolDefinition[];
+declare const outputSandboxToolHandlers: Record<string, ToolHandler>;
+declare function registerOutputSandboxTools(): void;
+
+export { ASSISTANT_PARITY_TOOLS, AUDIT_TOOLS, AUTOPILOT_TOOLS, type AgentData, type AssistResponseData, BRAIN_TOOLS, type BuildCapabilitiesOptions, COMPLIANCE_TOOLS, CONTEXT_SEARCH_TOOLS, type CapabilitiesDeps, type ContextValidationResult, DOCS_INTELLIGENCE_TOOLS, type FilteredWorkflows, type ListOptions, MARKETPLACE_TOOLS, type MCPServerOptions, type MCPToolResultWithMeta, METRICS_TOOLS, NOTIFICATION_TOOLS, OBSERVER_TOOLS, ONBOARDING_TOOLS, OUTPUT_SANDBOX_TOOLS, type OrchestratorStatus, type PRDData, type PolicyProfile, type ProgressInfo, type ProjectContextDisplay, QUALITY_INTELLIGENCE_TOOLS, type QualityGateResults, RBAC_TOOLS, RELEASE_TOOLS, type RegistryExports, SPRINT_EVIDENCE_KINDS, SPRINT_TOOLS, SWARM_TOOLS, SYNC_TOOLS, type SkillData, type SprintArtifactDetail, type SprintArtifactHistoryItem, type SprintArtifactResult, type SprintEvidenceKind, type SuccessOptions, type TodoItem, type ValidationResult, type WorkflowAccessContext, agentDetails, appendSprintEvidenceNote, assistResponse, buildCapabilities, buildDefaultCapabilities, clearCache, contextSearchToolHandlers, contextSummary, contextValidation, createServer, ensureSprintDir, error, generateProgressBar, getCompatibilityRegistryCandidatePaths, getLegacyRegistryCandidatePaths, getRegistryExports, getResourceHandlers, getResources, getToolHandlers, getTools, invokeTool, isRegistryPopulated, list, listSprintArtifacts, loadToolsFromDirectory, loopStatus, main, orchestratorStatus, outputSandboxToolHandlers, qualityResults, readSprintArtifactDetail, registerAssistantParityTools, registerAuditTools, registerAutopilotTools, registerBrainTools, registerComplianceTools, registerContextSearchTools, registerDocsIntelligenceTools, registerMarketplaceTools, registerMetricsTools, registerNotificationTools, registerObserverTools, registerOnboardingTools, registerOutputSandboxTools, registerQualityIntelligenceTools, registerRbacTools, registerReleaseTools, registerResource, registerSprintTools, registerSwarmTools, registerSyncTools, registerTool, resolveCompatibilityRegistry, resolveRuntimeRegistry, skillDetails, sprintDir, startStdioServer, success, todoList, trackTelemetry, validateDependencies, vitalsLine, warning };

package/dist/mcp/index.js

@@ -0,0 +1,2 @@
+'use strict';
+module.exports = require('../mcp-server.js');