Model Context Protocol (MCP) Server
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) Server provides a unified interface for AI agents to interact with FLEXT Quality tooling and ecosystem services. It exposes a set of standardized tools and resources that allow language models to perform semantic code searches, retrieve cross-session memory, execute quality hooks, and validate code against project rules.
The server operates as a FastMCP instance, acting as an orchestration layer between various internal engines (such as the FlextQualityRulesEngine and FlextQualityHookManager) and external MCP-capable clients like Claude Code. It resides within the src/flext_quality/mcp/ directory and is configured with the identity flext-quality.
Sources: AGENTS.md:16-17, tests/unit/test_mcp_layer.py:38, src/flext_quality/mcp/tools.py:16
Server Architecture
The MCP implementation uses a singleton pattern to ensure a consistent FastMCP server instance across the application. The architecture separates the server into dedicated namespaces for tools and resources, which are lazy-loaded upon access.
The diagram above shows the flow from a client through the singleton server instance to specific tools and resources.
Sources: src/flext_quality/mcp/init.py:28-32, tests/unit/test_mcp_layer.py:31-33, src/flext_quality/mcp/tools.py:20-25
Core Components
| Component | Responsibility |
|---|---|
FlextQualityMcpServer | Manages the FastMCP server lifecycle and provides the singleton instance. |
FlextQualityMcpTools | Contains static methods decorated via @_mcp.tool() to expose functional operations. |
FlextQualityMcpResources | Provides read-only access to system configurations and status via @_mcp.resource(). |
FlextQualityMcpClient | Utility for communicating with other MCP servers using the mcp-cli interface. |
Sources: src/flext_quality/mcp/tools.py:17-21, src/flext_quality/mcp/resources.py:18-20, src/flext_quality/integrations/mcp_client.py:23-27
MCP Tools
Tools enable active operations. The FlextQualityMcpTools class defines several capabilities that bridge FLEXT Quality with agent workflows.
Tool Definitions
| Tool Name | Parameters | Description |
|---|---|---|
search_memory | query, search_type, limit | Searches cross-session memory via claude-mem. |
search_code | query, limit | Performs semantic code search via claude-context. |
execute_hook | event, input_data | Manually triggers a registered hook (e.g., PreToolUse). |
validate_rules | path, context | Validates code files against the YAML-based rules engine. |
Sources: src/flext_quality/mcp/tools.py:24-95
Tool Execution Flow
The execute_hook tool interacts with the FlextQualityHookManager. When an event is triggered, the tool processes the result and returns either a continue flag or an error payload.
MCP Resources
Resources provide structured data about the current state or configuration of the quality environment. These are exposed via custom URI schemes.
settings://hooks: Returns the current hook configurations in JSON format, derived from theFlextQualityHookManager.settings://rules: Lists the current active quality rules from theFlextQualityRulesEngine.status://integrations: Reports the health and connection status forclaude-memandclaude-context.
Sources: src/flext_quality/mcp/resources.py:21-69
Data Models
The MCP server uses Pydantic-2 models for strict request/response validation. These models ensure that the communication between the agent and the tools adheres to defined contracts.
Model Specification
| Model Name | Field | Type | Description |
|---|---|---|---|
McpToolCall | server | str | ID of the server hosting the tool. |
tool | str | Name of the tool to invoke. | |
params | JsonMapping | Parameters for the invocation. | |
McpToolResult | success | bool | Indicates if the call was successful. |
data | StrMapping | None | Returned data payload. | |
error | str | None | Error message if failed. |
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:539-573
Integration with mcp-cli
FlextQualityMcpClient provides the infrastructure to call other MCP servers. It constructs shell commands for the mcp-cli executable to relay information.
- Command Building: The client generates commands like
mcp-cli call <server>/<tool> <params_json>. - Health Checks: It verifies if
mcp-cliis available on the systemPATH. - Exit Code Handling: Results are parsed differently based on process exit codes; non-zero codes are treated as failures and returned in the
McpToolResultformat.
Sources: src/flext_quality/integrations/mcp_client.py:41-55, src/flext_quality/integrations/mcp_client.py:146-170
Summary
The MCP Server acts as the primary communication bridge for agents within the FLEXT Quality platform. By exposing specialized tools for memory, code search, and rule validation, it integrates quality gates directly into the AI's contextual loop. The use of resources ensures that agents remain aware of the system's configuration and the health of external integrations.