MCP AI Agile Orchestrator

An integrated platform designed for governing AI-enhanced, iterative software development procedures, leveraging a resource-centric communication protocol built atop the FastMCP foundation.

Status Report

✅ Platform Transition Finalized: The shift from deprecated infrastructure to the optimized FastMCP implementation is complete. All preceding codebase artifacts and validation suites have been systematically retired.

System Synopsis

The MCP AI Agile Orchestrator employs a resource-oriented paradigm utilizing the official MCP SDK's FastMCP layer, emphasizing the following principles:

• RESTful Contract Design - Clear, easily navigable Uniform Resource Identifiers (URIs) for all data interactions.
• Resource-Dominant Structure - Architected to maximize efficiency in data retrieval operations and state representation.
• Operation-Centric Utilities - Tools are strictly reserved for actions that mandate state modification.

Core Capabilities

• Intelligent Specification Drafting: Produce and sustain exhaustive, AI-generated technical documentation.
• Project Scaffolding: Establish robust project layouts incorporating AI-created file hierarchies and assets.
• IDE Interoperability: Native connectivity features supporting multiple AI IDEs (e.g., Cursor, Windsurf, Cline).
• Lifecycle Tracking: Monitor the progress and status of agile work increments (stories).
• Hierarchical API Structure: Resources logically segmented according to RESTful conventions.
• Streamlined Connectivity: Direct mapping between high-level operations and resource URIs.
• Performance Uplift: Tuned specifically for efficient data access patterns common in development workflows.

Initiation Guide

To deploy the MCP AI Agile Orchestrator:

1. Install the package via pip: pip install mcp-ai-agile-orchestrator

2. Import the necessary functions in your application logic: ```python from mcp_ai_agile_orchestrator import invoke_tool, invoke_tool_synchronous

# Asynchronous invocation method data = await invoke_tool("fetch-project-metadata", parameters={})

# Synchronous invocation method data = invoke_tool_synchronous("fetch-project-metadata", parameters={}) ```

Orchestrator Client Parameterization

Critical Notice: Configuration Remediation Mandated

If you previously configured the legacy system, a mandatory update to your configuration artifacts is required. The fastmcp_server.py component has been eliminated during refactoring, and its responsibilities are now integrated directly into the primary package namespace.

Update your MCP client setup definition from the deprecated JSON structure:

{
    "name": "mcp-agile-flow",
    "server": {
        "type": "module",
        "module": "mcp_agile_flow.fastmcp_server",
        "entry_point": "run"
    }
}

To the revised format:

{
    "name": "mcp-ai-agile-orchestrator",
    "server": {
        "type": "module",
        "module": "mcp_ai_agile_orchestrator",
        "entry_point": "main"
    }
}

For users of Cursor, ensure the corresponding entry in your mcp.json file (typically located at ~/.cursor/mcp.json) is also adjusted:

"mcp-ai-agile-orchestrator": {
  "command": "/path/to/python",
  "args": [
    "-m",
    "mcp_ai_agile_orchestrator"  // Updated executable module path
  ],
  "autoApprove": [
    // ...
  ]
}

Execution via Command Line Interface

You possess the capability to initiate the backend service directly from the terminal:

# Standard execution (suppressed logging by default)
python -m mcp_ai_agile_orchestrator

# Activating standard informational logging
python -m mcp_ai_agile_orchestrator --verbose

# Diagnostic mode (maximum verbosity)
python -m mcp_ai_agile_orchestrator --debug

Exposed Toolset

The MCP AI Agile Orchestrator exposes the following functional instruments:

• fetch-project-metadata: Retrieves current project configurations, including file paths and environmental variables.
• setup-ide-environment: Establishes the foundational directory structure tailored for designated IDEs.
• install-ide-directives: Deploys essential AI rule files pertinent to specific development environments.
• synthesize-contextual-model: Parses project documentation to construct an internal, high-fidelity contextual understanding.
• reconfigure-mcp-profile: Manages the transition of MCP settings across different host IDEs.
• log-reasoning-step: Records a specific cognitive step for complex, sequential analytical tasks.
• retrieve-reasoning-log: Fetches all recorded cognitive steps from the active session.
• reset-reasoning-log: Clears all stored cognitive steps pertaining to the current session.
• query-reasoning-metrics: Obtains statistical summaries regarding the recorded cognitive steps.
• interpret-natural-command: Processes unstructured natural language input, routing requests to the correct tool agent.

Natural Language Interface

The Orchestrator incorporates advanced NL processing, allowing users to interact with tools conversationally without memorizing specific function names. The system automatically infers user intent and maps linguistic constructs to the appropriate tool invocation with necessary parameters.

Supported Command Categories

Profile Migration Sequences

For adapting MCP settings between disparate IDE platforms:

• "migrate mcp configuration over to claude-desktop"
• "shift configuration from cursor base to claude-desktop"
• "propagate mcp settings towards windsurf"
• "transfer configuration context to cline"
• "relocate mcp artifacts from cursor to roo"

If the originating IDE is unspecified, the default source is assumed to be "cursor".

Valid Targets: "cursor", "windsurf-next", "windsurf", "cline", "roo", and "claude-desktop".

Environment Setup Directives

To establish a fresh project workspace complete with configuration directives for a specific IDE:

• "bootstrap ide artifacts for claude"
• "deploy configuration rulesets for windsurf"
• "provision development workspace for cline"
• "initialize ruleset structure for copilot"

Metadata Retrieval Requests

To obtain the current operational parameters of the project:

• "fetch project metadata"
• "display current configuration"
• "project parameters"

Contextual Synthesis Commands

To initiate the deep analysis of project documentation:

• "synthesize context model"
• "analyze the current codebase context"
• "build contextual awareness"

Reasoning Documentation

To explicitly log a segment of analytical thought:

• "log reasoning step [detail your current thought process here]"

Usage Illustrations

Demonstrations of interaction via the programmatic interface:

from mcp_ai_agile_orchestrator import interpret_natural_command

# Transition configuration from Cursor to Claude
response = interpret_natural_command("migrate mcp configuration over to claude-desktop")

# Deploy rules for Windsurf
response = interpret_natural_command("deploy configuration rulesets for windsurf")

# Get project settings
response = interpret_natural_command("fetch project metadata")

# Synthesize the context model
response = interpret_natural_command("synthesize context model")

# Record a complex thought process
response = interpret_natural_command("log reasoning step how the latest dependency impacts core module X")

CLI Invocation

Natural language instructions can also be fed directly through the command-line tool:

python -m mcp_ai_agile_orchestrator interpret-natural-command "migrate mcp configuration over to claude-desktop"

Failure Modes

Should the intent engine fail to map the input to a known action, an explicit diagnostic message will be returned, advising the user to articulate the request with greater specificity.

Extensibility

The logic governing natural language interpretation resides within the processing_utils.py module, employing pattern matching via regular expressions. New command templates can be integrated by augmenting the map_nl_to_tool_call function with corresponding regex definitions.

Development Guidelines

To establish a development environment:

1. Clone the repository source: git clone https://github.com/yourusername/mcp-ai-agile-orchestrator.git cd mcp-ai-agile-orchestrator

2. Establish an isolated virtual environment: python -m venv .venv source .venv/bin/activate # Windows users: .venv\Scripts\activate

3. Install necessary development dependencies (editable mode): pip install -e ".[dev]"

4. Execute the test suite: pytest

5. Useful Makefile targets: make validate # Run all system validations make test-nl # Execute tests specific to natural language parsing make test-kernel # Execute core operational tests only make report-coverage # Generate code coverage statistics make purge-temp # Remove transient build artifacts make purge-full # Erase all artifacts including the environment make purge-legacy # Remove obsolete archived components

Licensing

This software is distributed under the terms of the MIT License - Refer to the LICENSE file for comprehensive details.