merge(next): MCP integration, async refactor, user experience improvements, and v2.0 release\n\n- Major: Model Context Protocol (MCP) integration for dynamic external tools/services (compatible with Cursor AI IDE)\n- Async refactor: all tool handlers and agent loop are async\n- User experience: emoji/logging improvements, spinner for MCP loading, graceful shutdown\n- Context: user queries now include current date/time\n- Docs: README and pyproject.toml updated for v2.0 and MCP\n- Many style, bugfix, and maintainability improvements

Author: AlessandroAnnini

CREATING_TOOLS.md

@@ -39,7 +39,7 @@ tool_definition = {
 }
 
 
-def handle_tool_call(input_data):
+def handle_call(input_data):
     """
     Process the tool call with the given input data.
 
@@ -76,9 +76,9 @@ TOOLS = [
 ]
 
 TOOL_HANDLERS = {
-    "bash": bash.handle_tool_call,
+    "bash": bash.handle_call,
     # ... other handler mappings
-    "my_tool": my_tool.handle_tool_call,  # Add your tool handler here
+    "my_tool": my_tool.handle_call,  # Add your tool handler here
 }
 ```
 
@@ -143,7 +143,7 @@ Follow these functional programming principles:
 Example of a handler with proper error handling:
 
 ```python
-def handle_tool_call(input_data):
+def handle_call(input_data):
     try:
         # Validate required inputs
         if "required_param" not in input_data:
@@ -176,7 +176,7 @@ API_KEY = os.getenv("MY_TOOL_API_KEY")
 BASE_URL = os.getenv("MY_TOOL_BASE_URL")
 
 # Then check these in your handler:
-def handle_tool_call(input_data):
+def handle_call(input_data):
     if not API_KEY or not BASE_URL:
         return "❌ Missing required environment variables in .env"
 
@@ -234,7 +234,7 @@ tool_definition = {
     }
 }
 
-def handle_tool_call(input_data):
+def handle_call(input_data):
     if not WEATHER_API_KEY:
         return "❌ Missing WEATHER_API_KEY environment variable"
 

README.md

@@ -1,13 +1,15 @@
 # Agent Loop
 
-> **An AI Agent with optional Human-in-the-Loop Safety**
+> **An AI Agent with optional Human-in-the-Loop Safety and Model Context Protocol (MCP) integration**
 
 ---
 
 ![Python](https://img.shields.io/badge/Python-3.8%2B-blue?logo=python)
 ![uv](https://img.shields.io/badge/uv-Package_Manager-7c4dff)
 ![Anthropic](https://img.shields.io/badge/Anthropic-API-orange)
 ![OpenAI](https://img.shields.io/badge/OpenAI-API-green?logo=openai)
+![MCP](https://img.shields.io/badge/Tool-MCP-4B8BBE?logo=protocols)
+**![Version](https://img.shields.io/badge/version-2.0.0-blue)**
 
 ## Tools
 
@@ -32,6 +34,9 @@
   - [Tools](#tools)
   - [Overview](#overview)
   - [Features](#features)
+  - [MCP (Model Context Protocol) Integration](#mcp-model-context-protocol-integration)
+    - [How it works](#how-it-works)
+    - [Example MCP config](#example-mcp-config)
   - [Available Tools](#available-tools)
   - [Installation](#installation)
     - [Option 1: Using the installation script (Recommended)](#option-1-using-the-installation-script-recommended)
@@ -41,6 +46,7 @@
   - [Configuration](#configuration)
     - [API Keys and Environment Variables](#api-keys-and-environment-variables)
     - [Custom System Prompt](#custom-system-prompt)
+    - [MCP Server Configuration](#mcp-server-configuration)
   - [Usage](#usage)
     - [Basic](#basic)
     - [Model Selection](#model-selection)
@@ -58,6 +64,7 @@
 - **Functional Programming:** Clean, composable, and testable code.
 - **DevOps Ready:** Integrates with Bash, Python, Docker, Git, Kubernetes, AWS, and more.
 - **Multi-Provider:** Supports both Anthropic Claude and OpenAI GPT models.
+- **MCP Integration:** Dynamically loads and uses tools/services from any MCP-compatible server (see below).
 
 ---
 
@@ -68,6 +75,52 @@
 - Debug mode for transparency (`--debug`)
 - Modular, extensible tool system
 - Functional programming style throughout
+- **MCP (Model Context Protocol) integration for external tool/service discovery and use**
+
+---
+
+## MCP (Model Context Protocol) Integration
+
+**New in v2.0!**
+
+Agent Loop can now connect to any number of MCP-compatible servers, dynamically discovering and using their services as tools. This means you can:
+
+- Add new capabilities (search, knowledge, automation, etc.) by simply running or configuring an MCP server.
+- Use tools from remote or local MCP servers as if they were built-in.
+- Aggregate services from multiple sources (e.g., Brave Search, Obsidian, custom servers) in one agent.
+
+> **ℹ️ The MCP server configuration format is identical to that used by [Cursor AI IDE](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers).**
+> See the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers) for more details and advanced options.
+
+### How it works
+
+- On startup, Agent Loop reads your MCP server configuration from `~/.config/agent-loop/mcp.json`.
+- For each server, it starts a session and lists available services.
+- Each service is registered as a tool (named `<server>-<service>`) and can be called by the agent or user.
+- All MCP tools are available alongside built-in tools.
+
+### Example MCP config
+
+```json
+{
+  "mcpServers": {
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": { "BRAVE_API_KEY": "..." }
+    },
+    "mcp-obsidian": {
+      "command": "npx",
+      "args": ["-y", "mcp-obsidian", "/path/to/obsidian-vault/"]
+    }
+  }
+}
+```
+
+- Place this file at `~/.config/agent-loop/mcp.json`.
+- Each server can be a local or remote MCP-compatible service.
+- All services/tools from these servers will be available in your agent session.
+- For more details, see the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers).
 
 ---
 
@@ -89,6 +142,7 @@
 | **aws_cli**           | Run AWS CLI v2 read-only commands to interact with AWS services |
 | **jira**              | Query JIRA via REST API using safe, read-only endpoints         |
 | **confluence**        | Query Atlassian Confluence Cloud via REST API (read-only)       |
+| **MCP**               | All services from configured MCP servers (see above)            |
 
 See [Creating Tools Guide](CREATING_TOOLS.md) for instructions on how to create your own tools.
 
@@ -258,6 +312,10 @@ nano ~/.config/agent-loop/SYSTEM_PROMPT.txt
 
 This allows you to give specific instructions or personality to the assistant. If this file doesn't exist, the default system prompt will be used.
 
+### MCP Server Configuration
+
+To enable MCP integration, create a file at `~/.config/agent-loop/mcp.json` as shown above. Each server entry should specify the command, arguments, and any required environment variables. All services from these servers will be available as tools in your agent session.
+
 ## Usage
 
 ### Basic

agent_loop/SYSTEM_PROMPT.txt

@@ -7,3 +7,4 @@ You have access to the following tools: bash, python, node, sympy, filesystem, h
 - ALWAYS ask for explicit user confirmation BEFORE any destructive or potentially destructive operation, even when not in safe mode.
 - Use functional programming principles in your suggestions and code.
 - Be concise, clear, and safety-conscious in all actions.
+- In general if you need to use some api, try with free ones except when told differently.

agent_loop/main.py

@@ -10,15 +10,24 @@
 import argparse
 from halo import Halo
 from dotenv import load_dotenv
+import asyncio
+from contextlib import AsyncExitStack, suppress
+from agent_loop.mcp_client import MCPManager
+import inspect
+import datetime
 
 load_dotenv(dotenv_path=os.path.expanduser("~/.config/agent-loop/.env"))
 
+mcp_manager = MCPManager()
+
 
 def user_input() -> List[Dict]:
     x = input("\ndev@agent-loop:~$ ")
     if x.lower() in {"exit", "quit"}:
-        print("Goodbye!")
+        print("👋 Goodbye!")
         raise SystemExit
+    now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    x = f"{x}\n(Current date and time: {now})"
     return [{"type": "text", "text": x}]
 
 
@@ -27,71 +36,57 @@ def create_llm():
     anthropic_model = os.getenv("ANTHROPIC_MODEL", "claude-3-7-sonnet-latest")
     openai_key = os.getenv("OPENAI_API_KEY")
     openai_model = os.getenv("OPENAI_MODEL", "gpt-4o")
-
     if not anthropic_key and not openai_key:
         raise EnvironmentError(
-            "No API keys found. Please set either ANTHROPIC_API_KEY or OPENAI_API_KEY "
-            "environment variables. If both are set, ANTHROPIC_API_KEY will be used."
+            "No API keys found. Please set either ANTHROPIC_API_KEY or OPENAI_API_KEY environment variables."
         )
-
-    # Check available API keys and select provider
     if anthropic_key:
-        # Use Anthropic if its key is available (priority)
         return create_anthropic_llm(anthropic_model, anthropic_key)
-    elif openai_key:
-        # Fallback to OpenAI if only its key is available
-        return create_openai_llm(openai_model, openai_key)
-    else:
-        # No API keys available
-        raise EnvironmentError(
-            "No API keys found. Please set either ANTHROPIC_API_KEY or OPENAI_API_KEY "
-            "environment variables. If both are set, ANTHROPIC_API_KEY will be used."
-        )
+    return create_openai_llm(openai_model, openai_key)
 
 
 def get_tool_description(tool_name: str) -> str:
-    """Return the description for a tool given its name."""
     for tool in TOOLS:
         if tool.get("name") == tool_name:
             return tool.get("description", "No description available.")
     return "No description available."
 
 
 def confirm_tool_execution(tool_name: str, input_data: Dict) -> bool:
-    """Prompt the user to confirm execution of a tool call."""
     description = get_tool_description(tool_name)
-    print(f"\n[CONFIRMATION REQUIRED]")
-    print(f"Tool: {tool_name}")
-    print(f"Description: {description}")
-    print(f"Input: {input_data}")
-    print("Do you want to execute this command? [y/N]: ", end="")
-    answer = input().strip().lower()
+    print(
+        f"\n⚠️ [CONFIRMATION REQUIRED]\nTool: {tool_name}\nDescription: {description}\nInput: {input_data}"
+    )
+    answer = input("Do you want to execute this command? [y/N]: ").strip().lower()
     return answer in {"y", "yes"}
 
 
-def handle_tool_call(tool_call: Dict, debug: bool = False, safe: bool = False) -> Dict:
+async def handle_tool_call(
+    tool_call: Dict, debug: bool = False, safe: bool = False
+) -> Dict:
     name = tool_call["name"]
     input_data = tool_call["input"]
+    print(f"🛠️ [Agent] Calling tool: {name} | Input: {input_data}")
     if debug:
         print(f"\n[Tool: {name}] Input: {input_data}\n")
-
     if safe and not confirm_tool_execution(name, input_data):
         return {
             "type": "tool_result",
             "tool_use_id": tool_call["id"],
             "content": [
                 {
                     "type": "text",
-                    "text": f"[SKIPPED] {name} command was not executed by user request.",
-                }
+                    "text": f"⚠️ [SKIPPED] {name} command was not executed by user request.",
+                },
             ],
         }
-
     handler = TOOL_HANDLERS.get(name)
     if not handler:
         raise ValueError(f"No handler for tool: {name}")
-
-    output = handler(input_data)
+    if inspect.iscoroutinefunction(handler):
+        output = await handler(input_data)
+    else:
+        output = handler(input_data)
     if debug:
         print(output)
     return {
@@ -101,7 +96,7 @@ def handle_tool_call(tool_call: Dict, debug: bool = False, safe: bool = False) -
     }
 
 
-def loop(llm_fn, debug: bool = False, safe: bool = False):
+async def loop(llm_fn, debug: bool = False, safe: bool = False):
     msg = user_input()
     while True:
         spinner = Halo(text="Thinking...", spinner="dots")
@@ -110,31 +105,48 @@ def loop(llm_fn, debug: bool = False, safe: bool = False):
             response, tool_calls = llm_fn(msg)
         finally:
             spinner.stop()
-        print("Agent:", response)
-
+        print(f"💬 Agent: {response}")
         if tool_calls:
             tool_results = [
-                handle_tool_call(tc, debug=debug, safe=safe) for tc in tool_calls
+                await handle_tool_call(tc, debug=debug, safe=safe) for tc in tool_calls
             ]
             msg = tool_results
         else:
             msg = user_input()
 
 
-def main():
-    parser = argparse.ArgumentParser(description="Agent Loop")
-    parser.add_argument("--debug", action="store_true", help="Show tool input/output")
-    parser.add_argument(
-        "--safe",
-        action="store_true",
-        help="Require confirmation before executing tools",
-    )
-    args = parser.parse_args()
+async def agent_main():
+    try:
+        async with AsyncExitStack() as exit_stack:
+            parser = argparse.ArgumentParser(description="Agent Loop")
+            parser.add_argument(
+                "--debug", action="store_true", help="Show tool input/output"
+            )
+            parser.add_argument(
+                "--safe",
+                action="store_true",
+                help="Require confirmation before executing tools",
+            )
+            args = parser.parse_args()
+            spinner = Halo(text="Loading MCP servers...", spinner="dots")
+            spinner.start()
+            try:
+                await mcp_manager.register_tools(exit_stack, debug=args.debug)
+            finally:
+                spinner.stop()
+            try:
+                await loop(create_llm(), debug=args.debug, safe=args.safe)
+            except KeyboardInterrupt:
+                print("\n👋 Interrupted. Goodbye!")
+    except asyncio.CancelledError:
+        pass
 
+
+def main():
     try:
-        loop(create_llm(), debug=args.debug, safe=args.safe)
+        asyncio.run(agent_main())
     except KeyboardInterrupt:
-        print("\nInterrupted. Goodbye!")
+        print("\n👋 Interrupted. Goodbye!")
 
 
 if __name__ == "__main__":