MCP Tools & Resources
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) layer in flext-quality provides a standardized interface for AI agents to interact with quality analysis workflows, code search, and session memory. It implements a set of specialized tools and resources that bridge the gap between Large Language Models (LLMs) and the internal quality orchestration engine.
This system serves as a unified orchestration platform for Claude Code tooling, enabling semantic search, hook execution, and rule validation through a common MCP server.
Sources: README.md, AGENTS.md:12-14, src/flext_quality/mcp/tools.py:17-19
Architecture and Infrastructure
The MCP implementation relies on a shared FastMCP server singleton named flext-quality. This server hosts all tools and resources, allowing external clients like Claude to discover and invoke functionality.
The diagram shows the relationship between the MCP server components and the underlying integration clients.
Sources: src/flext_quality/mcp/server.py, tests/unit/test_mcp_layer.py:34-45, src/flext_quality/_constants/values.py:53-55
Core Components
| Component | Class | Description |
|---|---|---|
| Server | FlextQualityMcpServer | Manages the FastMCP instance and lifecycle. |
| Tools | FlextQualityMcpTools | Namespace for executable operations (search, validate, execute). |
| Resources | FlextQualityMcpResources | Namespace for read-only data (configs, health status). |
| Client | FlextQualityMcpClient | Base client for communicating with external MCP servers via mcp-cli. |
Sources: src/flext_quality/mcp/init.py:17-36, src/flext_quality/integrations/mcp_client.py:27-32
MCP Tools
The FlextQualityMcpTools class provides functions decorated with @_mcp.tool(). These tools allow agents to perform active operations within the workspace.
Semantic Search Tools
The system integrates with claude-mem and claude-context to provide cross-session memory and semantic code search. These tools build commands that can be executed by the agent to retrieve relevant context.
search_memory: Searches cross-session memory for observations or entities.search_code: Performs semantic code search to find relevant snippets or definitions.
Sources: src/flext_quality/mcp/tools.py:23-49, src/flext_quality/mcp/tools.py:52-73
Workflow Orchestration Tools
execute_hook: Manually triggers a lifecycle hook (e.g.,PreToolUse) via theFlextQualityHookManager.validate_rules: Runs theFlextQualityRulesEngineagainst a specific path to identify quality violations based on YAML rule definitions.
Sources: src/flext_quality/mcp/tools.py:76-92, src/flext_quality/mcp/tools.py:95-112
Tool Parameters
| Tool | Parameter | Type | Default | Description |
|---|---|---|---|---|
search_memory | query | str | Required | The search query string. |
search_type | str | "observations" | Type of memory to search. | |
limit | int | 10 | Max results to return. | |
search_code | query | str | Required | Semantic search query. |
execute_hook | event | str | Required | Name of the hook event. |
validate_rules | path | str | Required | Filesystem path to validate. |
Sources: src/flext_quality/mcp/tools.py:23-112, src/flext_quality/_constants/values.py:48-49
MCP Resources
Resources provide read-only access to configuration and system status via URIs. These are implemented in the FlextQualityMcpResources class.
Configuration Access
The system exposes internal configurations as JSON resources, allowing agents to understand the active rules and hooks.
settings://hooks: Returns the current configuration fromFlextQualityHookManager.settings://rules: Lists all active rules loaded in theFlextQualityRulesEngine.
Sources: src/flext_quality/mcp/resources.py:23-40, src/flext_quality/mcp/resources.py:43-61
System Status
status://integrations: Checks the health of connected services. It performs a health check on bothFlextQualityClaudeMemClientandFlextQualityClaudeContextClient.
The sequence diagram illustrates the flow for checking integration health through the MCP resource layer.
Sources: src/flext_quality/mcp/resources.py:64-92
Command Execution Layer
The FlextQualityMcpClient handles the actual execution of tools when they require interaction with the mcp-cli. It builds shell commands and parses the output.
Result Parsing Logic
The client parses output from mcp-cli and converts it into a structured McpToolResult.
- Exit Code Check: If the exit code is non-zero, it returns a failure result with the error message.
- Object Parsing: Attempts to parse the output as a JSON object.
- List Parsing: If object parsing fails, it attempts to parse the output as a JSON list and coerces it into a sequence of mappings.
- Raw Output: Falls back to raw text if no JSON structure is detected.
Sources: src/flext_quality/integrations/mcp_client.py:157-184
Summary
The MCP Tools & Resources module provides the primary interaction layer for AI agents in the flext-quality ecosystem. By exposing semantic search, rule validation, and hook execution through a standard protocol, it enables automated quality maintenance and context-aware code analysis. The system is designed for reliability with built-in health checks and structured result parsing to ensure agents receive actionable data.
Sources: AGENTS.md:12-25, src/flext_quality/mcp/tools.py:1-10