Components

Codebase Component Breakdown

This document provides a breakdown of each Python file in the MCP Explorer codebase, explaining its significance and architectural role.

---

🛠️ Configuration & Core Files

1. config.py

The central configuration hub of the application. It manages dynamic configuration reloading based on environments.

• Significance: Loads variables from .env, .env.test, or .env.prod depending on the value of the MCP_ENV environment variable (falling back to .env if undefined).
• Key Objects: CONFIG (dictionary housing OLLAMA_URL, MONGODB_URI, LOG_LEVEL, and pathways to tools/MCP configuration files).

2. core/agent.py

The brain of the system.

• Significance: Defines the custom Agent class wrapper. It instantiates ChatOllama utilizing the gemma4:e4b model and binds it to a list of dynamically resolved tools using LangGraph's create_react_agent.
• Key Methods:
  • ainvoke(prompt, thread_id, callbacks): Starts the agent as an asynchronous generator utilizing astream_events to yield granular execution events (model responses, token outputs, tool inputs/outputs) back to the caller.

3. core/logger.py

The diagnostic tracing console callback.

• Significance: Extends LangChain's BaseCallbackHandler to format and print colored, structured execution logs directly to the system CLI.
• Key Methods:
  • on_chain_start() / on_chain_end(): Logs execution boundaries of sub-graphs.
  • on_tool_start() / on_tool_end(): Traces the exact input and outputs of standard/MCP tool execution.

---

🔌 Loader Components

4. core/mcp_loader.py

Connects the agent to external tool suites using the Model Context Protocol.

• Significance: Parses mcpConfig.json, spawns each configured MCP server (e.g. SQLite, local scripts) as an independent OS process, establishes stdin/stdout channels, and maps their exposed JSON-RPC tools into LangChain compatible tool interfaces.

5. core/tool_loader.py

The dynamic initializer for standard LangChain integrations.

• Significance: Resolves issues with third-party tools that require code-level adjustments (such as configuring User-Agent credentials for Wikipedia or overriding Arxiv query parameters).
• Key Methods:
  • load_standard_tools(config_path): Reads toolsConfig.json, compiles and executes the tool_inits Python code snippets dynamically via exec(), then registers these standard tools into the agent scope.

---

🖥️ User Interface

6. ui/app.py

The frontend coordinator.

• Significance: Orchestrates Chainlit's user lifecycle events.
• Workflow:
  • @cl.on_chat_start: Initializes tools, establishes MCP servers context, and instantiates the Agent object.
  • @cl.on_message: Triggers agent.ainvoke, streaming response tokens in real-time to the user's browser. In the finally block, it parses the underlying langfuse_handler.last_trace_id and manually updates the trace payload in Langfuse (assigning trace input and the name "MCP Explorer Agent").