NagaAgent

NagaAgent provides a super AI secretary experience with streaming tool calls, knowledge graph memory, Live2D visuals, and voice interaction. The MCP integration exposes several modular capabilities (Agent tools) that can be invoked by the LLM through the MCP adapter. Core components include: a tool loop that parses in-text tool calls and routes them to appropriate agents, a GRAG-based memory system for structured knowledge capture and retrieval, and a MCP-enabled tool registry that lists built-in agents like weather_time, open_launcher, game_guide, online_search, crawl4ai, playwrisght_master, vision, mqtt_tool, and office_doc. The server coordinates streaming results, context compression, and asynchronous tool execution, enabling multi-step tool invocation within a single chat session. To use it, start the NagaAgent MCP server and interact with the UI-enabled features (conversation, mind view, skill workshop) or connect your own frontend to the same MCP endpoints for tool execution and memory retrieval.

Prerequisites

• Python 3.11 (>=3.11, <3.12)
• Optional: uv for faster dependency installation
• Optional: Neo4j for local knowledge graph memory

Installation steps

1. Clone the repository

git clone https://github.com/Xxiii8322766509/NagaAgent.git
cd NagaAgent

2. Install frontend dependencies (if you plan to use the included UI)

cd frontend
npm install
cd ..

3. Install backend dependencies and set up environment Option A: Use the provided setup script (auto-detects environment, creates a virtual environment, installs dependencies)

python setup.py

Option B: Use uv (recommended for development)

uv sync

Option C: Manual installation

python -m venv .venv
# Windows
.\.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
pip install -r requirements.txt

4. Prepare configuration Copy the example config to config.json and insert your API credentials (e.g., DeepSeek/OpenAI-compatible API settings). Example:

{
  "api": {
    "api_key": "your-api-key",
    "base_url": "https://api.deepseek.com",
    "model": "deepseek-v3.2"
  }
}

5. Run the MCP server

# from project root, using the recommended command defined in mcp_config
python -m NagaAgent

Notes

• If you already have a frontend, run it separately (e.g., CD into frontend and npm run dev).
• The setup supports multiple environments; choose the one that fits your dev or deployment workflow.
• OpenNeo4j or remote memory backends may require additional configuration (connection URL, credentials).

Tips and common issues:

• Ensure Python 3.11 is used; the project specifies compatibility with 3.11.x.
• If using uv, install and run via uv sync to accelerate dependency installation.
• For memory features, Neo4j must be configured locally or use a cloud/remote graph; ensure network access.
• The config.json example must be present at the project root or as expected by the launch script; verify paths if the MCP runner reports missing config.
• The tool loop supports up to 5 iterations per prompt for streaming tool calls; adjust max_loop_stream if you customize the flow.
• When integrating with other frontends, reuse the MCP endpoints for tool execution and memory access to ensure consistent tool routing.