MCP Dual-Cycle Reasoner
The MCP Dual-Cycle Reasoner server enhances AI agent autonomy and self-awareness through metacognitive monitoring and case-based reasoning.
• Metacognitive Monitoring: Initialize, update, and stop monitoring of agent cognitive processes, tracking actions, context, and goals with real-time insights and session summaries • Intelligent Loop Detection: Identify repetitive patterns or stagnation using statistical, pattern-based, or hybrid methods with configurable thresholds and progress indicators • Experience Management: Store and retrieve problem-solution cases with detailed metadata, utilizing semantic matching for efficient case-based reasoning • System Management: Access current monitoring status and statistics, configure detection parameters, and reset the engine state for fresh sessions
Integrated with GitHub Actions for CI/CD pipeline automation, as shown by the workflow badge in the README.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Dual-Cycle Reasoner monitor my reasoning on solving this math puzzle"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server implementing the Dual-Cycle Metacognitive Reasoning Framework for autonomous agents. This tool empowers agents with greater self-awareness and reliability through intelligent loop detection and experience acquisition.
Description
The MCP Dual-Cycle Reasoner is a sophisticated tool designed to enhance the autonomy and reliability of AI agents. By implementing a dual-cycle metacognitive framework, it provides agents with the ability to monitor their own cognitive processes, detect when they are stuck in repetitive loops, and learn from past experiences to make better decisions.
The framework consists of two main components:
Sentinel: Monitors the agent's actions and detects anomalies, such as action repetition, state invariance, and progress stagnation.
Adjudicator: Manages a case base of past experiences, allowing the agent to store and retrieve solutions to previously encountered problems.
This server is built with TypeScript and leverages high-performance libraries for statistical analysis, natural language processing, and semantic similarity, enabling advanced features like entropy-based anomaly detection, NLI-based text analysis, and intelligent case management.
Related MCP server: verifiable-thinking-mcp
Key Features
📊 Advanced Statistical Analysis: Entropy-based anomaly detection and time series analysis.
🧠 Enhanced Case-Based Reasoning: Semantic similarity matching with NLI-based text analysis.
🎯 Multi-Strategy Detection: Statistical, pattern-based, and hybrid loop detection.
📈 Time Series Analysis: Trend detection and cyclical pattern recognition.
🔧 Configurable Detection: Domain-specific thresholds and progress indicators.
🎨 Intelligent Case Management: Quality scoring, deduplication, and usage-based optimization.
🚀 High-Performance Libraries: Built with
simple-statistics,natural,compromise, and HuggingFace Transformers.
Tech Stack
Language: TypeScript
Framework: Node.js
Server: FastMCP for SSE transport
NLP and Machine Learning:
@huggingface/transformers: For NLI-based semantic analysisnatural: For sentiment analysis and tokenizationcompromise: For natural language processing
Statistics:
simple-statistics: For statistical calculationsml-matrix: For matrix operations
Development Tools:
jest: For testingeslint: For lintingprettier: For code formattingzod: For schema validation
Installation
To get the project running locally, follow these steps:
Clone the repository:
git clone https://github.com/cyqlelabs/mcp-dual-cycle-reasoner.git cd mcp-dual-cycle-reasonerInstall dependencies:
npm installBuild the project:
npm run build
Usage
Running the Server
You can run the server in two modes:
HTTP Stream (Default):
npm startThe server will start on port 8080.
Stdio:
npm start -- --stdio
Using with Claude Desktop
Add the following to your Claude Desktop MCP configuration:
{
"mcpServers": {
"dual-cycle-reasoner": {
"command": "npx",
"args": ["@cyqlelabs/mcp-dual-cycle-reasoner"]
}
}
}For stdio transport, add the --stdio flag to the args array.
Available Tools
Core Monitoring Tools
start_monitoring
Initialize metacognitive monitoring of an agent's cognitive process.
Input Schema:
{
goal: string; // Current goal being pursued
initial_beliefs?: string[]; // Initial beliefs about the task
}process_trace_update
Main monitoring function—processes cognitive trace updates from the agent.
Input Schema:
{
last_action: string; // Latest action name
current_context?: string; // Current environment context
goal: string; // Current goal being pursued
window_size?: number; // Monitoring window size (default: 10)
}Return Payload:
Returns a JSON object indicating if intervention is required and details about any detected loop.
{
"intervention_required": true,
"loop_detected": {
"detected": true,
"type": "action_repetition",
"confidence": 0.85,
"details": "Loop detected via parameter_repetition: 57% anomaly score...",
"actions_involved": ["click_submit_button"]
}
}stop_monitoring
Stop metacognitive monitoring and get a session summary.
Input Schema: {}
Loop Detection Tools
detect_loop
Detect if the agent is stuck in a loop using various strategies.
Input Schema:
{
current_context?: string; // Current environment context
goal: string; // Current goal being pursued
detection_method?: "statistical" | "pattern" | "hybrid"; // Detection method (default: "hybrid")
}Return Payload:
Returns a LoopDetectionResult object as a JSON string.
{
"detected": true,
"type": "action_repetition",
"confidence": 0.85,
"details": {
"dominant_method": "parameter_repetition",
"anomaly_score": 0.57,
"actions_involved_count": 1,
"recent_actions_count": 10,
"metrics": {
"semantic_repetition": 0.6,
"parameter_repetition": 0.8
}
},
"actions_involved": ["click_submit_button"]
}configure_detection
Configure loop detection parameters and domain-specific progress indicators.
Input Schema:
{
progress_indicators?: string[]; // default: []
min_actions_for_detection?: number; // default: 5
alternating_threshold?: number; // default: 0.5
repetition_threshold?: number; // default: 0.4
progress_threshold_adjustment?: number; // default: 0.2
semantic_intents?: string[]; // default: []
}Enhanced Experience Management
store_experience
Store a case for future case-based reasoning with enhanced metadata and quality scoring.
Input Schema:
{
problem_description: string;
solution: string;
outcome: boolean;
context?: string;
difficulty_level?: "low" | "medium" | "high";
}retrieve_similar_cases
Retrieve similar cases using advanced semantic matching and filtering.
Input Schema:
{
problem_description: string;
max_results?: number; // default: 5
context_filter?: string;
difficulty_filter?: "low" | "medium" | "high";
outcome_filter?: boolean;
min_similarity?: number; // default: 0.6
}Return Payload:
Returns an array of Case objects as a JSON string.
[
{
"id": "case-123",
"problem_description": "Form submission button not responding to clicks",
"solution": "Ensure all required fields are filled correctly.",
"outcome": true,
"context": "registration_form",
"difficulty_level": "medium",
"similarity_metrics": {
"combined_similarity": 0.92
}
}
]System Tools
get_monitoring_status
Get the current monitoring status and statistics.
Input Schema: {}
Return Payload:
Returns a JSON string with the current monitoring status, including is_monitoring, current_goal, trace_length, and intervention_count.
{
"is_monitoring": true,
"current_goal": "Complete user registration process on website",
"trace_length": 15,
"intervention_count": 2,
"recent_actions": [
{ "type": "click_submit_button", "timestamp": 1678886400000 },
{ "type": "click_submit_button", "timestamp": 1678886401000 }
]
}reset_engine
Reset the dual-cycle engine state.
Input Schema: {}
Example Usage Scenario
Here's a complete example showing how to use the dual-cycle reasoner to monitor an autonomous agent and build up experience over time:
1. Initial Setup and Configuration
// Configure detection parameters for your domain
await configure_detection({
progress_indicators: ['page_loaded', 'form_submitted', 'data_extracted'],
min_actions_for_detection: 3,
alternating_threshold: 0.6,
repetition_threshold: 0.3,
semantic_intents: [
'navigating to page',
'clicking element',
'filling form field',
'submitting form',
'validating input',
'handling popup',
'extracting data',
'waiting for response',
],
});
// Start monitoring the agent's goal
await start_monitoring({
goal: 'Complete user registration process on website',
});2. Monitoring Agent Actions
// Monitor each action the agent takes
await process_trace_update({
last_action: 'click_signup_button',
current_context: 'homepage',
goal: 'Complete user registration process on website',
});
// ... agent continues actions ...
// Agent gets stuck clicking submit repeatedly
await process_trace_update({
last_action: 'click_submit_button',
current_context: 'registration_form',
goal: 'Complete user registration process on website',
});
// Returns: {
// "intervention_required": true,
// "loop_detected": {
// "detected": true,
// "type": "action_repetition",
// "confidence": 0.85,
// "details": {
// "dominant_method": "parameter_repetition",
// "anomaly_score": 0.57,
// "actions_involved_count": 1,
// "recent_actions_count": 10,
// "metrics": {
// "semantic_repetition": 0.6,
// "parameter_repetition": 0.8
// }
// },
// "actions_involved": ["click_submit_button"]
// }
// }3. Storing and Retrieving Experiences
// Store a successful experience
await store_experience({
problem_description: 'Email validation error blocking form submission',
solution: 'Check email format and retry with valid email address',
outcome: true,
context: 'registration_form',
difficulty_level: 'medium',
});
// When a loop is detected, retrieve similar cases for recovery
const similarCases = await retrieve_similar_cases({
problem_description: 'Form submission button not responding to clicks',
max_results: 3,
context_filter: 'registration_form',
outcome_filter: true,
});Understanding Loop Detection
When the process_trace_update tool detects a potential loop, it returns a detailed loop_detected object. Understanding the components of this object can help you diagnose and debug agent behavior.
Here's a quick guide to the key metrics in the details object:
dominant_method: The primary method that triggered the loop detection (e.g.,semantic_repetition,state_invariance).anomaly_score: An overall score (0-1) representing the confidence that the agent's recent actions are part of a loop. It's a weighted average of multiple detection methods.actions_involved_count: The number of recent actions identified as being part of the detected loop.recent_actions_count: The total number of recent actions analyzed.metrics: An object containing the raw scores from the different detection methods, such as:semantic_repetition: The percentage of recent actions that are semantically similar to each other.parameter_repetition: The percentage of similarity between the parameters of semantically similar actions.exact_repetition: The percentage of recent actions that are exact, character-for-character duplicates.cyclical_pattern: The score (0-1) indicating the presence of repeating sequences of actions.oscillation_pattern: The score (0-1) indicating the presence of oscillating (back-and-forth) actions.alternating_pattern: The score (0-1) indicating the presence of alternating action patterns.
Contributing
Contributions are welcome! Please read the contributing guidelines and ensure all tests pass before submitting a pull request.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Available Tools
9 toolsconfigure_detectionB
Configure loop detection parameters and domain-specific progress indicators
Inputs: alternating_threshold, min_actions_for_detection, progress_indicators, progress_threshold_adjustment, +2 more.
detect_loopARead-onlyIdempotent
Detect if the agent is stuck in a loop using various strategies
Inputs: goal (required), current_context, detection_method.
get_monitoring_statusARead-onlyIdempotent
Get current monitoring status and statistics
Inputs: no named parameters.
process_trace_updateC
Process a cognitive trace update from the agent (main monitoring function)
Inputs: goal (required), last_action (required), current_context, window_size.
reset_engineADestructiveIdempotent
Reset the dual-cycle engine state
Inputs: no named parameters.
retrieve_similar_casesBRead-onlyIdempotent
Retrieve similar cases from the case base
Inputs: problem_description (required), max_results.
start_monitoringB
Start metacognitive monitoring of an agent's cognitive process
Inputs: goal (required), initial_beliefs.
stop_monitoringAIdempotent
Stop metacognitive monitoring and get session summary
Inputs: no named parameters.
store_experienceB
Store a case for future case-based reasoning
Inputs: outcome (required), problem_description (required), solution (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools have distinct purposes, but there is some potential overlap between 'detect_loop' and 'process_trace_update' as both involve monitoring cognitive processes. The descriptions clarify their roles, with 'detect_loop' focused on loop detection and 'process_trace_update' handling general trace updates, but an agent might occasionally confuse them in practice.
All tool names follow a consistent verb_noun pattern using snake_case, such as 'configure_detection', 'detect_loop', and 'start_monitoring'. This uniformity makes the set predictable and easy to navigate, with no deviations in naming conventions.
With 9 tools, the count is well-scoped for a dual-cycle reasoner server, covering configuration, monitoring, detection, and case management. Each tool appears to serve a specific function without redundancy, making the set appropriately sized for the domain.
The tool set provides comprehensive coverage for metacognitive monitoring and reasoning, including start/stop, detection, status retrieval, and case storage. A minor gap exists in tools for modifying or deleting stored cases, but core workflows are well-supported, allowing agents to work around this limitation.
Maintenance
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Agent-to-agent reasoning-as-a-service: chain-of-thought, analysis, and decision support.
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that provides Claude with a dedicated space for structured thinking during complex problem-solving tasks, helping improve its reasoning capabilities.140 npm16MIT
- AlicenseBqualityNot gradedmaintenanceMCP server for structured reasoning with cognitive trap detection, verification, and context compression541 npm1-
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server providing pre-curated canonical memory, prose/code provenance checking, and benchmark metrics to improve accuracy and reduce costs across AI tools.AGPL 3.0
- AlicenseBqualityDmaintenanceAn MCP server for detecting retry loops and analyzing iteration patterns in agentic coding workflows, providing structured debugging intelligence to improve repair attempts.164MIT