# oraichain/orai-mcp architecture

> Architecture diagram of the GitHub repository oraichain/orai-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oraichain/orai-mcp
- Repository: https://github.com/oraichain/orai-mcp

## Overview

##### Main Components
- MCP Server: This is the core package (located in packages/mcp-server) that implements the Model Context Protocol. It handles incoming requests from AI clients, interacts with multiple blockchain networks, and manages tasks such as retrieving wallet balances, transferring funds, deploying smart contracts, and bridging assets.
- Agent Tools: This package (found in packages/agent-tools) is a collection of ready-to-use blockchain interaction tools. It includes specific sub-components (organized under oraichain) like:
– Authentication (auth)
– Banking operations (bank – including balance queries and transfers)
– Staking mechanisms (staking – with operations for delegation, undelegation, etc.)
– Transaction handling (tx – signing, broadcasting and voting)
- Agent Kit: Located in packages/agent-kit, this component acts as a development kit to help build custom AI agents with blockchain capabilities. It offers interfaces, utilities, and adherence to best practices for consistent development.

##### External Interfaces and Dependencies
- Environment & Configuration: Highlight the use of a .env file in the MCP server package, where parameters such as port number and RPC_URL are configured.
- Developer and Deployment Tools: Include the runtime environment details (Node.js, pnpm workspaces, and Turborepo for monorepo management) to emphasize that this is built in TypeScript with modern tooling.

##### Interactions Between Components
- The MCP Server should be represented as the central hub that receives incoming requests (e.g., from AI clients or integrations like Claude Desktop).
- Agent Kit with the MCP Server and Agent Tools. Explain that while the Agent Kit is primarily used by developers to build or customize AI agents, it helps ensure standardized communication with the underlying blockchain operations in the other two packages.

##### Architectural Patterns and Practices
- Separation of Concerns: Emphasize that each package focuses on a specific area (MCP Server for protocol handling, Agent Tools for blockchain operations, and Agent Kit for development support).
- Extensibility: Note that the design is modular, allowing for future packages or additional blockchain integrations; for example, adding new DeFi protocols or AI enhancements.

##### Detailed Architectural Elements
- Nodes/Blocks:
- External Clients/Integrations (e.g., AI Agents, Claude Desktop integration)
- MCP Server: Responsible for blockchain protocol handling and serving requests.
- Agent Tools: Subsections for authentication, banking, staking, and transaction operations.
- Agent Kit: Development resources for crafting custom AI agents.
- External Blockchain Networks: Represented as external systems interacting with Agent Tools.
- Relationships:
- How MCP Server acts as the orchestrator by delegating tasks to Agent Tools.
- Bidirectional communication between Agent Kit and MCP Server/Agent Tools if applicable for enhancing agent capabilities.
- Annotations:
- An explanation for each component’s role and the reason behind its interaction.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    EClients("AI Agents & Claude Desktop"):::external
    Blockchain("Blockchain Networks (RPC)"):::external

    %% Monorepo Packages
    subgraph "MCP Server Package"
        MCP("MCP Server"):::server
        Config("Configuration (.env)"):::config
    end

    subgraph "Agent Tools Package"
        AT("Agent Tools Main Module"):::tools
        Auth("Authentication"):::tools
        Bank("Banking Operations"):::tools
        Staking("Staking Mechanisms"):::tools
        Tx("Transaction Handling"):::tools
    end

    AK("Agent Kit"):::kit

    %% Internal relationships within Agent Tools Package
    AT --> Auth
    AT --> Bank
    AT --> Staking
    AT --> Tx

    %% External interactions and data flow
    EClients -->|"API_Request"| MCP
    MCP -->|"Delegates_BlockchainOps"| AT
    MCP -->|"Integrates_with"| AK
    AK -->|"Utilizes_Tools"| AT
    AT -->|"Interacts_with"| Blockchain
    MCP -->|"ConfiguredBy"| Config

    %% Tooling/Configuration (annotated)
    Tools("Node.js, TypeScript, pnpm, Turborepo"):::config

    %% Styles
    classDef external fill:#ffcc00,stroke:#000,stroke-width:2px;
    classDef server fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef tools fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef kit fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef config fill:#d3d3d3,stroke:#333,stroke-width:2px;

    %% Click Events
    click MCP "https://github.com/oraichain/orai-mcp/tree/master/packages/mcp-server"
    click Config "https://github.com/oraichain/orai-mcp/blob/master/packages/mcp-server/.env.example"
    click AT "https://github.com/oraichain/orai-mcp/tree/master/packages/agent-tools"
    click Auth "https://github.com/oraichain/orai-mcp/tree/master/packages/agent-tools/oraichain/auth"
    click Bank "https://github.com/oraichain/orai-mcp/tree/master/packages/agent-tools/oraichain/bank"
    click Staking "https://github.com/oraichain/orai-mcp/tree/master/packages/agent-tools/oraichain/staking"
    click Tx "https://github.com/oraichain/orai-mcp/tree/master/packages/agent-tools/oraichain/tx"
    click AK "https://github.com/oraichain/orai-mcp/tree/master/packages/agent-kit"
```
