foundry-mcp 0.3.3__py3-none-any.whl

foundry_mcp/schemas/sdd-spec-schema.json

@@ -0,0 +1,386 @@
+{
+  "$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"
+    },
+    "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."
+        },
+        "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"
+        },
+        "status": {
+          "type": "string",
+          "description": "Workflow status for the specification."
+        },
+        "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."
+            },
+            "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"
+              ]
+            },
+            "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,164 @@
+"""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.core.feature_flags import get_flag_service
+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 _apply_feature_flag_overrides_from_env() -> None:
+    """Apply comma-separated feature flag overrides from `FEATURE_FLAGS`."""
+
+    raw = os.environ.get("FEATURE_FLAGS")
+    if not raw:
+        return
+
+    flag_service = get_flag_service()
+    for name in [part.strip() for part in raw.split(",") if part.strip()]:
+        flag_service.set_override("anonymous", name, True)
+
+
+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()
+
+    _apply_feature_flag_overrides_from_env()
+    _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",
+]

foundry_mcp/tools/unified/__init__.py

@@ -0,0 +1,71 @@
+"""Unified action-based MCP tools."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .authoring import register_unified_authoring_tool
+from .error import register_unified_error_tool
+from .health import register_unified_health_tool
+from .journal import register_unified_journal_tool
+from .metrics import register_unified_metrics_tool
+from .plan import register_unified_plan_tool
+from .pr import register_unified_pr_tool
+from .provider import register_unified_provider_tool
+from .environment import register_unified_environment_tool
+from .lifecycle import register_unified_lifecycle_tool
+from .verification import register_unified_verification_tool
+from .review import register_unified_review_tool
+from .spec import register_unified_spec_tool
+from .server import register_unified_server_tool
+from .test import register_unified_test_tool
+
+
+if TYPE_CHECKING:  # pragma: no cover - import-time typing only
+    from mcp.server.fastmcp import FastMCP
+    from foundry_mcp.config import ServerConfig
+
+
+def register_unified_tools(mcp: "FastMCP", config: "ServerConfig") -> None:
+    """Register consolidated tool families."""
+
+    register_unified_health_tool(mcp, config)
+    register_unified_plan_tool(mcp, config)
+    register_unified_pr_tool(mcp, config)
+    register_unified_error_tool(mcp, config)
+    register_unified_metrics_tool(mcp, config)
+    register_unified_journal_tool(mcp, config)
+    register_unified_authoring_tool(mcp, config)
+    register_unified_review_tool(mcp, config)
+    register_unified_spec_tool(mcp, config)
+
+    from importlib import import_module
+
+    _task_router = import_module("foundry_mcp.tools.unified.task")
+    _task_router.register_unified_task_tool(mcp, config)
+    register_unified_provider_tool(mcp, config)
+    register_unified_environment_tool(mcp, config)
+    register_unified_lifecycle_tool(mcp, config)
+    register_unified_verification_tool(mcp, config)
+    register_unified_server_tool(mcp, config)
+    register_unified_test_tool(mcp, config)
+
+
+__all__ = [
+    "register_unified_tools",
+    "register_unified_health_tool",
+    "register_unified_plan_tool",
+    "register_unified_pr_tool",
+    "register_unified_error_tool",
+    "register_unified_metrics_tool",
+    "register_unified_journal_tool",
+    "register_unified_authoring_tool",
+    "register_unified_review_tool",
+    "register_unified_spec_tool",
+    "register_unified_provider_tool",
+    "register_unified_environment_tool",
+    "register_unified_lifecycle_tool",
+    "register_unified_verification_tool",
+    "register_unified_server_tool",
+    "register_unified_test_tool",
+]