fraim 2.0.277 → 2.0.278

package/dist/src/mcp/tool-schemas.js

@@ -0,0 +1,376 @@
+"use strict";
+/**
+ * MCP Tool Definitions
+ *
+ * This file contains the JSON schemas for all tools exposed by the FRAIM MCP Server.
+ * Centralizing these definitions improves readability and maintainability of the McpService.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getToolDefinitions = void 0;
+const readOnlyClosedWorldAnnotations = {
+    readOnlyHint: true,
+    openWorldHint: false,
+    destructiveHint: false,
+};
+const writeClosedWorldAnnotations = {
+    readOnlyHint: false,
+    openWorldHint: false,
+    destructiveHint: false,
+};
+const readOnlyOpenWorldAnnotations = {
+    readOnlyHint: true,
+    openWorldHint: true,
+    destructiveHint: false,
+};
+const writeOpenWorldAnnotations = {
+    readOnlyHint: false,
+    openWorldHint: true,
+    destructiveHint: false,
+};
+const getToolDefinitions = (options = {}) => {
+    const surface = options.surface ?? 'local-proxy';
+    const isLocalProxySurface = surface === 'local-proxy';
+    const sessionIdProperty = isLocalProxySurface
+        ? {
+            sessionId: {
+                type: 'string',
+                description: 'Active FRAIM session ID. Required on local-proxy runtime calls.'
+            }
+        }
+        : {};
+    const requiredWithSession = (fields) => isLocalProxySurface
+        ? ['sessionId', ...fields]
+        : fields;
+    const fraimConnectDescription = isLocalProxySurface
+        ? `Bootstrap and initialize a FRAIM session and obtain the sessionId used by active FRAIM workflow tools. Use this after explicit FRAIM activation: the user invoked FRAIM, named a FRAIM job, asked for FRAIM job recommendations, or the active surface selected a FRAIM job. Must be called before any FRAIM workflow tool calls. For ordinary requests, do not start a FRAIM session or scan the catalog.
+
+Example:
+{
+  "agent": {"name": "Claude", "model": "claude-3.5-sonnet"}
+}`
+        : `Bootstrap and initialize a FRAIM session and obtain the sessionId used by active FRAIM workflow tools. Use this after explicit FRAIM activation: the user invoked FRAIM, named a FRAIM job, asked for FRAIM job recommendations, or the active surface selected a FRAIM job. Must be called before any FRAIM workflow tool calls. For ordinary requests, do not start a FRAIM session or scan the catalog.
+
+Hosted marketplace clients may call this with only agent information. If machine or repository context is omitted, FRAIM creates a hosted marketplace session context automatically.
+
+Example:
+{
+  "agent": {"name": "ChatGPT", "model": "gpt-5"}
+}`;
+    return [
+        {
+            name: 'fraim_connect',
+            description: fraimConnectDescription,
+            annotations: writeClosedWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    agent: {
+                        type: 'object',
+                        description: 'Agent identification',
+                        properties: {
+                            name: {
+                                type: 'string',
+                                description: 'Agent name (e.g., "Claude", "Cursor", "Kiro", "Windsurf", "Antigravity", "Grok")',
+                                examples: ['Claude', 'Cursor', 'Kiro', 'Windsurf', 'Antigravity', 'Grok']
+                            },
+                            model: {
+                                type: 'string',
+                                description: 'Model name/version (e.g., "claude-3.5-sonnet", "gpt-4", "cursor-small")',
+                                examples: ['claude-3.5-sonnet', 'gpt-4', 'cursor-small', 'kiro-agent']
+                            },
+                            version: {
+                                type: 'string',
+                                description: 'Agent version if available',
+                                examples: ['1.0.0', '2024.12.1']
+                            }
+                        },
+                        required: ['name', 'model'],
+                        additionalProperties: true
+                    },
+                    ...(isLocalProxySurface
+                        ? {}
+                        : {
+                            machine: {
+                                type: 'object',
+                                description: 'Optional machine specifications. Hosted marketplace sessions default this when omitted.',
+                                properties: {
+                                    hostname: {
+                                        type: 'string',
+                                        description: 'Machine hostname'
+                                    },
+                                    platform: {
+                                        type: 'string',
+                                        description: 'Platform (win32, darwin, linux)'
+                                    },
+                                    memory: {
+                                        type: 'number',
+                                        description: 'Total memory in bytes (auto-detected by local proxy)'
+                                    },
+                                    cpus: {
+                                        type: 'number',
+                                        description: 'CPU count (auto-detected by local proxy)'
+                                    }
+                                },
+                                required: ['hostname', 'platform', 'memory', 'cpus'],
+                                additionalProperties: true
+                            },
+                            repo: {
+                                type: 'object',
+                                description: 'Optional repository context. Hosted marketplace sessions default to FRAIM public catalog context when omitted.',
+                                properties: {
+                                    url: {
+                                        type: 'string',
+                                        description: 'Git repository URL'
+                                    },
+                                    owner: {
+                                        type: 'string',
+                                        description: 'Repository owner'
+                                    },
+                                    namespace: {
+                                        type: 'string',
+                                        description: 'Repository namespace (GitLab group/subgroup path)'
+                                    },
+                                    name: {
+                                        type: 'string',
+                                        description: 'Repository name'
+                                    },
+                                    projectPath: {
+                                        type: 'string',
+                                        description: 'Repository project path (GitLab, for example group/subgroup/repo)'
+                                    },
+                                    branch: {
+                                        type: 'string',
+                                        description: 'Current branch'
+                                    }
+                                },
+                                required: ['url'],
+                                additionalProperties: true
+                            }
+                        }),
+                    issueTracking: {
+                        type: 'object',
+                        description: 'Optional issue tracking context for split-provider setups (for example Jira + GitHub)',
+                        properties: {
+                            provider: {
+                                type: 'string',
+                                description: 'Issue tracking provider',
+                                enum: ['jira', 'github', 'ado', 'linear', 'gitlab']
+                            },
+                            owner: {
+                                type: 'string',
+                                description: 'Issue tracking owner (GitHub)'
+                            },
+                            name: {
+                                type: 'string',
+                                description: 'Issue tracking repository or project name'
+                            },
+                            organization: {
+                                type: 'string',
+                                description: 'Issue tracking organization (ADO)'
+                            },
+                            project: {
+                                type: 'string',
+                                description: 'Issue tracking project (ADO)'
+                            },
+                            namespace: {
+                                type: 'string',
+                                description: 'Issue tracking namespace (GitLab group/subgroup path)'
+                            },
+                            projectPath: {
+                                type: 'string',
+                                description: 'Issue tracking project path (GitLab, for example group/subgroup/repo)'
+                            },
+                            baseUrl: {
+                                type: 'string',
+                                description: 'Base URL for issue tracker (for example myorg.atlassian.net)'
+                            },
+                            projectKey: {
+                                type: 'string',
+                                description: 'Project key or namespace for issue IDs'
+                            }
+                        },
+                        required: ['provider'],
+                        additionalProperties: true
+                    }
+                },
+                required: ['agent']
+            }
+        },
+        {
+            name: 'get_fraim_file',
+            description: `Get a specific skill, rule, or reference file from the FRAIM registry by path.
+
+For running FRAIM jobs, use get_fraim_job instead — do NOT call get_fraim_file for job execution.
+
+Examples:
+- get_fraim_file({ path: "skills/communication/active-listening.md" })
+- get_fraim_file({ path: "rules/local-development.md" })`,
+            annotations: readOnlyClosedWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty,
+                    path: {
+                        type: 'string',
+                        description: 'Path to the file (e.g., skills/communication/active-listening.md, rules/local-development.md, templates/specs/FEATURESPEC-TEMPLATE.md)'
+                    },
+                    raw: {
+                        type: 'boolean',
+                        description: 'If true, returns the raw unparsed content without any MCP headers or parsing.'
+                    }
+                },
+                required: requiredWithSession(['path'])
+            }
+        },
+        {
+            name: 'get_fraim_job',
+            description: `Execute a named FRAIM job after explicit FRAIM activation. Call this tool whenever the user asks to run, start, or execute a named FRAIM job. Returns phased instructions — follow each phase and call seekMentoring to advance phases.
+
+Do NOT use get_fraim_file to load job content. Always use get_fraim_job for job execution.
+
+Examples:
+- get_fraim_job({ job: "feature-specification" })
+- get_fraim_job({ job: "technical-design" })
+- get_fraim_job({ job: "feature-implementation" })`,
+            annotations: readOnlyClosedWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty,
+                    job: {
+                        type: 'string',
+                        description: 'Job name (e.g., "feature-implementation", "technical-design", "feature-specification")'
+                    },
+                    raw: {
+                        type: 'boolean',
+                        description: 'If true, returns the raw unparsed markdown content of the job.'
+                    }
+                },
+                required: requiredWithSession(['job'])
+            }
+        },
+        {
+            name: 'list_fraim_jobs',
+            description: `List the FRAIM job catalog. Use this when the user asks what FRAIM jobs are available, asks for FRAIM job recommendations, or after explicit FRAIM activation when local stubs are unavailable. Do not use this for ordinary requests. If no exact or high-confidence job match exists, do not pick the nearest job; continue normally or ask one concise clarification.`,
+            annotations: readOnlyClosedWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty
+                },
+                required: requiredWithSession([])
+            }
+        },
+        {
+            name: 'file_fraim_github_issue',
+            description: `Create a GitHub issue in the FRAIM repository.
+      
+Use this tool when you need to report a bug, request a feature from FRAIM. Do not use this tool to file issues in other repositories.
+Supports dry-run mode to preview the operation.
+
+This tool accepts text only. If visual evidence is needed, upload images to a stable shared HTTPS URL first and include those URLs in the issue body as markdown images or plain links. Do not include local file paths or base64-encoded image data in the issue body.`,
+            annotations: writeOpenWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty,
+                    title: {
+                        type: 'string',
+                        description: 'Title of the issue'
+                    },
+                    body: {
+                        type: 'string',
+                        description: 'Body/Content of the issue. If visual evidence is needed, include shared HTTPS image URLs in the body; do not include local file paths or base64 image data.'
+                    },
+                    labels: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of labels to apply'
+                    },
+                    dryRun: {
+                        type: 'boolean',
+                        description: 'If true, simulates the creation without actually notifying GitHub'
+                    }
+                },
+                required: requiredWithSession(['title', 'body'])
+            }
+        },
+        {
+            name: 'list_my_fraim_github_issues',
+            description: `List issues the current FRAIM user filed into the FRAIM GitHub repository.
+
+This tool is the read-side companion to file_fraim_github_issue. Use it when you need a simple list of issues filed by the current FRAIM user into the FRAIM repository.
+
+Returns only:
+- issue number
+- title
+- status
+- created date
+
+Do not use this tool for other repositories or external project issue trackers.`,
+            annotations: readOnlyOpenWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty,
+                    limit: {
+                        type: 'integer',
+                        description: 'Optional maximum number of issues to return. Defaults to 20 and is capped at 100.'
+                    }
+                },
+                required: requiredWithSession([])
+            }
+        },
+        {
+            name: 'seekMentoring',
+            description: `Get the instructions for the current FRAIM phase, advance to the next phase, or ask for help on the active phase after fraim_connect starts the session.`,
+            annotations: writeClosedWorldAnnotations,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...sessionIdProperty,
+                    jobName: {
+                        type: 'string',
+                        description: 'Name of the job you are following',
+                    },
+                    jobId: {
+                        type: 'string',
+                        description: 'Job ID returned by get_fraim_job. Required for tracking job execution and completion.'
+                    },
+                    issueNumber: {
+                        type: 'string',
+                        description: 'Issue number or Task ID you are working on'
+                    },
+                    currentPhase: {
+                        type: 'string',
+                        description: 'The phase you are currently in or have just finished (e.g., "implement-scoping"). For initial workflow start, use "starting".'
+                    },
+                    status: {
+                        type: 'string',
+                        description: 'Status of your work in the current phase',
+                        enum: ['starting', 'complete', 'incomplete', 'failure']
+                    },
+                    findings: {
+                        type: 'object',
+                        description: 'Your findings, summaries, or results from the current phase (required for status="complete")',
+                        properties: {
+                            uncertainties: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Any unclear aspects that need clarification'
+                            }
+                        },
+                        additionalProperties: true
+                    },
+                    evidence: {
+                        type: 'object',
+                        description: 'Structured evidence or data collected (e.g., prospect counts, test results). Submit phases should put review artifacts in evidence.reviewHandoff rather than printing raw JSON to the user. Retrospective phases may put follow-on job recommendations in evidence.nextJobRecommendations (array of { jobId, label, reason?, contextSummary? }, max 3) so the work surface can offer them as next steps.',
+                        additionalProperties: true
+                    }
+                },
+                required: requiredWithSession(['jobName', 'jobId', 'issueNumber', 'currentPhase', 'status'])
+            }
+        }
+    ];
+};
+exports.getToolDefinitions = getToolDefinitions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.277",
+  "version": "2.0.278",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {
@@ -19,8 +19,9 @@
     "dist/src/services/",
     "dist/src/api/",
     "dist/src/middleware/",
-    "dist/src/models/",
-    "dist/src/types/",
+    "dist/src/models/",
+    "dist/src/mcp/",
+    "dist/src/types/",
     "dist/src/utils/",
     "bin/fraim.js",
     "public/first-run/",