foundry-mcp 0.8.22__py3-none-any.whl

foundry_mcp/schemas/intake-schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Intake Item Schema",
+  "description": "Schema for bikelane intake items - fast work idea capture",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "id",
+    "title",
+    "status",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "intake-v1",
+      "description": "Schema version identifier, fixed value 'intake-v1'"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^intake-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$",
+      "description": "Unique intake item identifier in format 'intake-<uuid4>'"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 140,
+      "description": "Brief title for the intake item (1-140 characters)"
+    },
+    "description": {
+      "type": ["string", "null"],
+      "maxLength": 2000,
+      "description": "Detailed description of the work item (max 2000 characters)"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["new", "dismissed"],
+      "description": "Item status: 'new' for triage queue, 'dismissed' for archived"
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["p0", "p1", "p2", "p3", "p4"],
+      "default": "p2",
+      "description": "Priority level from p0 (highest) to p4 (lowest), defaults to p2"
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 32,
+        "pattern": "^[a-z0-9_-]+$"
+      },
+      "maxItems": 20,
+      "uniqueItems": true,
+      "default": [],
+      "description": "Tags for categorization (max 20 items, each 1-32 chars, lowercase alphanumeric with _ and -)"
+    },
+    "source": {
+      "type": ["string", "null"],
+      "maxLength": 100,
+      "description": "Origin of the intake item (e.g., 'user-note', 'slack', 'email') max 100 chars"
+    },
+    "requester": {
+      "type": ["string", "null"],
+      "maxLength": 100,
+      "description": "Person or entity who requested the work (max 100 chars)"
+    },
+    "idempotency_key": {
+      "type": ["string", "null"],
+      "maxLength": 64,
+      "description": "Optional client-provided key for deduplication (max 64 chars)"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": ".*Z$",
+      "description": "ISO 8601 UTC timestamp with Z suffix when item was created"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": ".*Z$",
+      "description": "ISO 8601 UTC timestamp with Z suffix of last update"
+    }
+  },
+  "additionalProperties": false
+}

foundry_mcp/schemas/sdd-spec-schema.json

@@ -0,0 +1,414 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SDD Spec File Schema",
+  "description": "Schema for SDD (Spec-Driven Development) JSON specification files",
+  "type": "object",
+  "required": [
+    "spec_id",
+    "generated",
+    "last_updated",
+    "hierarchy"
+  ],
+  "properties": {
+    "spec_id": {
+      "type": "string",
+      "pattern": "^[\\w-]+-\\d{4}-\\d{2}-\\d{2}-\\d{3}$",
+      "description": "Unique specification identifier: {feature}-{YYYY-MM-DD}-{nnn}"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable specification title"
+    },
+    "generated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when spec was generated"
+    },
+    "last_updated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last update"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "in_progress", "completed", "blocked"],
+      "description": "Overall spec status (computed from task progress)"
+    },
+    "progress_percentage": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "Overall progress as percentage (0-100), computed from completed/total tasks"
+    },
+    "current_phase": {
+      "type": ["string", "null"],
+      "pattern": "^phase-\\d+(?:-[\\w-]+)*$",
+      "description": "ID of the currently active phase (first in_progress or first pending)"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Optional spec-level metadata",
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "Specification title retained for backward compatibility."
+        },
+        "description": {
+          "type": "string",
+          "description": "High-level description of the specification."
+        },
+        "mission": {
+          "type": "string",
+          "description": "Concise mission/goal statement for the entire specification."
+        },
+        "objectives": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Key objectives or acceptance criteria for the spec."
+        },
+        "complexity": {
+          "type": "string",
+          "description": "Relative complexity indicator."
+        },
+        "estimated_hours": {
+          "type": "number",
+          "minimum": 0
+        },
+        "owner": {
+          "type": "string"
+        },
+        "assumptions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Design assumptions and constraints for this spec (e.g., single-user workflow, feature branch ownership)"
+        },
+        "revision_history": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "version",
+              "date",
+              "changelog"
+            ],
+            "properties": {
+              "version": {
+                "type": "string",
+                "description": "Version number (e.g., 1.0, 1.1, 2.0)"
+              },
+              "date": {
+                "type": "string",
+                "format": "date-time",
+                "description": "ISO 8601 timestamp of revision"
+              },
+              "author": {
+                "type": "string",
+                "description": "Who made the revision"
+              },
+              "changelog": {
+                "type": "string",
+                "description": "Description of changes made in this revision"
+              },
+              "modified_by": {
+                "type": "string",
+                "description": "Tool or command that made the modification (e.g., sdd modify-spec)"
+              },
+              "review_triggered_by": {
+                "type": "string",
+                "description": "Path to review report that triggered this revision (if applicable)"
+              }
+            }
+          },
+          "description": "Version history tracking spec modifications over time"
+        }
+      },
+      "additionalProperties": true
+    },
+    "hierarchy": {
+      "type": "object",
+      "description": "Task hierarchy tree",
+      "patternProperties": {
+        "^spec-root$": {
+          "$ref": "#/definitions/node"
+        },
+        "^phase-\\d+(?:-[\\w-]+)*$": {
+          "$ref": "#/definitions/node"
+        },
+        "^task-\\d+(?:-\\d+)+$": {
+          "$ref": "#/definitions/node"
+        },
+        "^verify-\\d+(?:-\\d+)+$": {
+          "$ref": "#/definitions/node"
+        }
+      }
+    }
+  },
+  "definitions": {
+    "node": {
+      "type": "object",
+      "required": [
+        "type",
+        "title",
+        "status",
+        "parent",
+        "children",
+        "total_tasks",
+        "completed_tasks",
+        "metadata"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Node identifier matching the key in hierarchy"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "spec",
+            "phase",
+            "group",
+            "task",
+            "subtask",
+            "verify"
+          ],
+          "description": "Node type in hierarchy"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable title"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "in_progress",
+            "completed",
+            "blocked"
+          ],
+          "description": "Current status"
+        },
+        "parent": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Parent node ID (null only for spec-root)"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Array of child node IDs"
+        },
+        "metadata": {
+          "type": "object",
+          "description": "Node-specific metadata",
+          "default": {},
+          "properties": {
+            "purpose": {
+              "type": "string",
+              "description": "High-level intent or goal for the node's work."
+            },
+            "risk_level": {
+              "type": "string",
+              "description": "Qualitative risk indicator (e.g., low, medium, high)."
+            },
+            "estimated_hours": {
+              "type": "number",
+              "minimum": 0
+            },
+            "complexity": {
+              "type": "string",
+              "description": "Relative complexity label."
+            },
+            "task_category": {
+              "type": "string",
+              "enum": [
+                "investigation",
+                "implementation",
+                "refactoring",
+                "decision",
+                "research"
+              ],
+              "description": "Category of task work."
+            },
+            "file_path": {
+              "type": "string",
+              "description": "Primary file impacted by the node."
+            },
+            "description": {
+              "type": "string",
+              "description": "Task or node description."
+            },
+            "acceptance_criteria": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Acceptance criteria for the node."
+            },
+            "details": {
+              "oneOf": [
+                {"type": "string"},
+                {
+                  "type": "array",
+                  "items": {"type": "string"}
+                }
+              ],
+              "description": "Free-form detail text for subtasks and tasks. Can be a string or array of strings."
+            },
+            "changes": {
+              "type": "string",
+              "description": "Summary of expected code or documentation changes."
+            },
+            "reasoning": {
+              "type": "string",
+              "description": "Supporting rationale or justification."
+            },
+            "owner": {
+              "type": "string",
+              "description": "Optional owner or assignee."
+            },
+            "verification_type": {
+              "type": "string",
+              "enum": [
+                "run-tests",
+                "fidelity",
+                "manual"
+              ]
+            },
+            "agent": {
+              "type": "string",
+              "description": "Automation agent to run for verification."
+            },
+            "mcp_tool": {
+              "type": "string",
+              "description": "MCP tool to invoke for verification (e.g., mcp__foundry-mcp__spec-review-fidelity)."
+            },
+            "command": {
+              "type": "string",
+              "description": "Command or instructions for automated verification."
+            },
+            "expected": {
+              "type": "string",
+              "description": "Expected outcome of verification."
+            },
+            "scope": {
+              "type": "string",
+              "description": "Scope identifier for fidelity verification."
+            },
+            "target": {
+              "type": "string",
+              "description": "Target identifier for verification scope."
+            },
+            "status": {
+              "type": "string",
+              "description": "Optional workflow status for metadata (distinct from node status)."
+            },
+            "started_at": {
+              "type": "string",
+              "format": "date-time",
+              "description": "ISO 8601 timestamp when work started."
+            },
+            "completed_at": {
+              "type": "string",
+              "format": "date-time",
+              "description": "ISO 8601 timestamp when work completed."
+            },
+            "actual_hours": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Actual hours spent on the node."
+            },
+            "on_failure": {
+              "$ref": "#/definitions/on_failure_actions"
+            }
+          },
+          "additionalProperties": true
+        },
+        "total_tasks": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total tasks in this subtree"
+        },
+        "completed_tasks": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Completed tasks in this subtree"
+        },
+        "dependencies": {
+          "type": "object",
+          "properties": {
+            "blocked_by": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "depends": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "blocks": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "on_failure_actions": {
+      "type": "object",
+      "description": "Configurable actions to take when verification fails",
+      "properties": {
+        "consult": {
+          "type": "boolean",
+          "description": "Whether to trigger AI consultation for debugging (default: false)",
+          "default": false
+        },
+        "revert_status": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "in_progress",
+            "blocked"
+          ],
+          "description": "Status to revert the parent task to on failure (default: in_progress)",
+          "default": "in_progress"
+        },
+        "max_retries": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 5,
+          "description": "Maximum number of automatic retry attempts (default: 0)",
+          "default": 0
+        },
+        "notify": {
+          "type": "string",
+          "enum": [
+            "log"
+          ],
+          "description": "Notification method on failure (default: log)",
+          "default": "log"
+        },
+        "continue_on_failure": {
+          "type": "boolean",
+          "description": "Whether to continue with other verifications if this one fails (default: false)",
+          "default": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

foundry_mcp/server.py

@@ -0,0 +1,150 @@
+"""FastMCP server for foundry-mcp.
+
+This server exposes the unified 17-router tool surface described in
+`mcp/capabilities_manifest.json`.
+
+Note: Legacy per-tool-name MCP endpoints are intentionally not registered.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from foundry_mcp.config import ServerConfig, get_config
+from foundry_mcp.core.observability import audit_log, get_observability_manager
+from foundry_mcp.resources.specs import register_spec_resources
+from foundry_mcp.prompts.workflows import register_workflow_prompts
+from foundry_mcp.tools.unified import register_unified_tools
+
+logger = logging.getLogger(__name__)
+
+
+def _init_observability(config: ServerConfig) -> None:
+    """Initialize the observability stack from server configuration."""
+
+    obs_config = config.observability
+    if not obs_config.enabled:
+        logger.debug("Observability disabled in configuration")
+        return
+
+    manager = get_observability_manager()
+    manager.initialize(obs_config)
+
+    tracing_status = "enabled" if manager.is_tracing_enabled() else "disabled"
+    metrics_status = "enabled" if manager.is_metrics_enabled() else "disabled"
+    logger.info(
+        "Observability initialized: tracing=%s, metrics=%s",
+        tracing_status,
+        metrics_status,
+    )
+
+
+def _init_error_collection(config: ServerConfig) -> None:
+    """Initialize the error collection infrastructure."""
+
+    err_config = config.error_collection
+    if not err_config.enabled:
+        logger.debug("Error collection disabled in configuration")
+        return
+
+    try:
+        from foundry_mcp.core.error_collection import get_error_collector
+        from foundry_mcp.core.error_store import get_error_store
+
+        storage_path = err_config.get_storage_path()
+        store = get_error_store(storage_path)
+        collector = get_error_collector()
+        collector.initialize(store, err_config)
+        logger.info("Error collection initialized: storage_path=%s", storage_path)
+    except Exception as exc:
+        # Don't fail server startup due to optional error collection
+        logger.warning("Failed to initialize error collection: %s", exc)
+
+
+def _init_metrics_persistence(config: ServerConfig) -> None:
+    """Initialize the metrics persistence infrastructure."""
+
+    metrics_config = config.metrics_persistence
+    if not metrics_config.enabled:
+        logger.debug("Metrics persistence disabled in configuration")
+        return
+
+    try:
+        from foundry_mcp.core.metrics_persistence import initialize_metrics_persistence
+        from foundry_mcp.core.metrics_store import get_metrics_store
+
+        collector = initialize_metrics_persistence(metrics_config)
+        if collector is None:
+            return
+
+        storage_path = metrics_config.get_storage_path()
+        store = get_metrics_store(storage_path)
+        deleted_count = store.cleanup(
+            retention_days=metrics_config.retention_days,
+            max_records=metrics_config.max_records,
+        )
+
+        if deleted_count > 0:
+            logger.info("Metrics cleanup: removed %s old records", deleted_count)
+
+        logger.info("Metrics persistence initialized: storage_path=%s", storage_path)
+    except Exception as exc:
+        # Don't fail server startup due to optional persistence
+        logger.warning("Failed to initialize metrics persistence: %s", exc)
+
+
+def create_server(config: Optional[ServerConfig] = None) -> FastMCP:
+    """Create and configure the FastMCP server instance."""
+
+    if config is None:
+        config = get_config()
+
+    config.setup_logging()
+
+    _init_observability(config)
+    _init_error_collection(config)
+    _init_metrics_persistence(config)
+
+    mcp = FastMCP(name=config.server_name)
+
+    # Unified-only tool surface
+    register_unified_tools(mcp, config)
+
+    # Resources and prompts
+    register_spec_resources(mcp, config)
+    register_workflow_prompts(mcp, config)
+
+    logger.info("Server created: %s v%s", config.server_name, config.server_version)
+    return mcp
+
+
+def main() -> None:
+    """Main entry point for the foundry-mcp server."""
+
+    try:
+        config = get_config()
+        server = create_server(config)
+
+        logger.info("Starting %s v%s", config.server_name, config.server_version)
+        audit_log("tool_invocation", tool="server_start", version=config.server_version)
+
+        server.run()
+
+    except KeyboardInterrupt:
+        logger.info("Server shutdown requested")
+        get_observability_manager().shutdown()
+        sys.exit(0)
+    except BaseException as exc:
+        logger.error("Server error: %s: %s", type(exc).__name__, exc)
+        audit_log("tool_invocation", tool="server_error", error=str(exc), success=False)
+        get_observability_manager().shutdown()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

foundry_mcp/tools/__init__.py

@@ -0,0 +1,10 @@
+"""MCP tool registration surface.
+
+Only the unified 17-router tool surface is exported.
+"""
+
+from foundry_mcp.tools.unified import register_unified_tools
+
+__all__ = [
+    "register_unified_tools",
+]