mini-agent-mcp

# Mini Agent MCP [](https://www.npmjs.com/package/mini-agent-mcp) [](https://www.npmjs.com/package/mini-agent-mcp) [](https://github.com/Microbiosis/mini-agent-mcp/blob/main/LICENSE) [](https://github.com/Microbiosis/mini-agent-mcp) [](https://modelcontextprotocol.io) [](https://nodejs.org) > **Mini Agent MCP** > **Service Category**: Search Tools / AI Agent / Developer Tools > **Source Address**: https://github.com/Microbiosis/mini-agent-mcp > **Deployment**: Deployable, no local environment dependencies, supports one-click deployment to the cloud. ## Service Introduction Mini Agent MCP is an intelligent agent service that integrates a ReAct small agent and follows the Model Context Protocol (MCP). The agent can autonomously call multiple tools to complete complex multi-step tasks, supporting both LLM-driven and rule engine modes. ## Service Description This is an intelligent agent server based on the MCP protocol, integrating 7 built-in tools (calculator, text analysis, text conversion, unit conversion, date and time, random generation, and ReAct Agent) and 4 AnySearch search tools. It supports multi-step reasoning (up to 8 steps), can autonomously combine and call tools to complete tasks, and supports MCP Sampling multi-model communication without requiring a server-side API Key. ## ✨ Core Features - **🧮 Built-in Tools** — calculator, text analysis, text conversion, unit conversion, date and time, random generation (6 tools without API Key requirements) - **🤖 ReAct Agent** — supports Thought → Action → Observation multi-step reasoning loop, can combine up to 8 tool steps - **🔍 AnySearch** — integrates AnySearch through MCP Streamable HTTP, supports general search, batch search (1-5 parallel), URL content extraction, and vertical domain search - **🔗 Multi-model Communication** — supports MCP Sampling (client-side model) and Direct HTTP (proprietary API) LLM communication methods, compatible with OpenAI and Anthropic API formats - **☁️ Deployable** — no local environment dependencies, can be deployed with one click to the ModelScope MCP platform, automatically generating SSE access addresses - **🔁 Automatic Retries** — tool calls fail and automatically retry 3 times with exponential backoff (1s → 2s → 4s) ## 🚀 Quick Start ### Method 1: MCP Client Configuration (Recommended) #### ZCode ```json { "mcpServers": { "mini-agent-mcp": { "type": "stdio", "command": "npx", "args": ["mini-agent-mcp"], "env": { "ANYSEARCH_API_KEY": "", "LLM_API_FORMAT": "openai", "LLM_API_KEY": "", "LLM_BASE_URL": "", "LLM_MODEL": "" } } } } ``` > When using ZCode, the agent prioritizes MCP Sampling (ZCode's LLM). After configuring `LLM_*`, it can be used as a fallback: Sampling fails and automatically switches to Direct HTTP. ### Method 2: .env File (fallback) When the MCP client does not pass environment variables, create a `.env` file in the server's working directory: ```bash # Copy template cp .env.example .env # Edit .env and fill in values ANYSEARCH_API_KEY=xs_xxxxx LLM_API_KEY=lc_xxxxx LLM_BASE_URL=https://api.longcat.chat/openai LLM_MODEL=LongCat-2.0-Preview ``` > The server automatically reads the `.env` file when starting, without requiring client-side variable passing. ### Method 3: Local Development ```bash git clone https://github.com/Microbiosis/mini-agent-mcp.git cd mini-agent-mcp npm install npm run build node dist/index.js # Run MCP server node dist/index.js --test # Run tests ``` ## 🛠️ Tool List ### Built-in Tools | Tool Name | Description | Parameters | |----------|------|------| | `calculator` | Safe mathematical expression evaluation (supports sqrt, sin, cos, pi, etc.) | `expression` (string, required) | | `text_stats` | Text statistical analysis (word count, word frequency, sentence count, etc.) | `text` (string, required) | | `text_transform` | Text conversion (case, reversal, sorting, deduplication, etc.) | `text` (string, required), `operation` (string, required) | | `unit_convert` | Unit conversion (length, weight, temperature, data) | `value` (number, required), `from` (string, required), `to` (string, required) | | `datetime_info` | Date and time query, formatting, and difference calculation | `operation` (string, required) | | `random_gen` | Random number, UUID, password, list extraction | `operation` (string, required) | | `run_agent` | ReAct Agent — autonomously calls the above tools to complete multi-step tasks | `task` (string, required) | ### AnySearch Tools (auto-discovery) Automatically connects to `https://api.anysearch.com/mcp` for dynamic discovery at startup: | Tool Name | Description | Parameters | |----------|------|------| | `anysearch_search` | General search (supports financial, academic, legal, and other vertical domains) | `query` (string, required), `max_results` (number, optional) | | `anysearch_batch_search` | 1-5 independent queries parallel search | `queries` (array, required) | | `anysearch_extract` | URL webpage content extraction (Markdown, up to 50,000 characters) | `url` (string, required) | | `anysearch_get_sub_domains` | Query vertical domain directory (must call before domain search) | `domain` (string, optional) | ## 🤖 Agent Workflow ``` User Task → [Thought: Analyze task] → [Action: Select tool] → [Execute tool] → [Observation: Observe result] → [Thought: Continue reasoning] → ... (up to 8 steps) → [Final Answer: Final answer] ``` ## 📡 LLM Communication Modes The agent supports three LLM communication methods, **automatically selecting by priority**: ### Method 1: MCP Sampling (Recommended) The server makes a `sampling/createMessage` request through the MCP protocol, letting the **client (e.g., ZCode / Claude Desktop / Cursor)** call the LLM on behalf. - **Zero configuration** — server does not need API Key, does not need to know the model name - **Client decides model** — client uses the user's selected model - **Supports multi-model communication** — client can flexibly choose different models for reasoning > This is the native multi-model communication method of MCP. As long as the client supports sampling, the agent can use the client's LLM. ### Method 2: Direct HTTP (fallback) The server directly calls the LLM API. Requires setting environment variables: | Variable | Required | Description | Example | |------|------|------|------| | `LLM_API_KEY` | Yes | API key | `lc_xxxxx` | | `LLM_BASE_URL` | Yes | API endpoint | `https://api.longcat.chat/openai` | | `LLM_MODEL` | Yes | Model name | `LongCat-2.0-Preview` | | `LLM_API_FORMAT` | No | `openai` or `anthropic` (automatically identified if not filled) | `openai` | ### Method 3: Rule Engine (safety net) Automatically enabled without LLM, processes common tasks through pattern matching (mathematical calculation, unit conversion, time query, password/UUID generation, text analysis, multi-step complex tasks). ### Summary | Scenario | LLM Mode | |------|----------| | Running as MCP server in ZCode / Claude / Cursor | MCP Sampling (client-side model) ✅ | | Running independently + set `LLM_API_KEY` + `LLM_BASE_URL` + `LLM_MODEL` | Direct HTTP | | Running independently + environment variables not set | Rule engine mode (no LLM) | ## 🌐 Supported LLM Providers ### OpenAI Chat Completions Format `LLM_API_FORMAT=openai` or not set (automatically identified) | Provider | `LLM_BASE_URL` | `LLM_MODEL` Example | |--------|----------------|------------------| | **LongCat** | `https://api.longcat.chat/openai` | `LongCat-2.0-Preview` | | **OpenAI** | `https://api.openai.com/v1` | `gpt-4o-mini` | | **DeepSeek** | `https://api.deepseek.com/v1` | `deepseek-chat` | | **SenseNova** | `https://token.sensenova.cn/v1` | `sensenova-6.7-flash-lite` | | **kimi** | `https://api.moonshot.cn/v1` | `moonshot-v1-8k` | | **Ollama** | `http://localhost:11434/v1` | `llama3.2` | ### Anthropic Messages Format `LLM_API_FORMAT=anthropic` or not set (URL contains `/anthropic` automatically identified) | Provider | `LLM_BASE_URL` | `LLM_MODEL` Example | Authentication Header | |--------|----------------|------------------|--------| | **LongCat (Anthropic)** | `https://api.longcat.chat/anthropic` | `LongCat-2.0-Preview` | `x-api-key` | | **SenseNova (Anthropic)** | `https://token.sensenova.cn` | `sensenova-6.7-flash-lite` | `Bearer` | | **Anthropic** | `https://api.anthropic.com` | `claude-sonnet-4-20250514` | `Bearer` | > **Format automatically identified**: code automatically judges which format to use to send requests based on `LLM_BASE_URL`: > - URL contains `/anthropic` → Anthropic format > - Others → OpenAI format ## 🔧 Environment Variables | Variable | Required | Description | Default Value | |------|------|------|--------| | `ANYSEARCH_API_KEY` | No | AnySearch API Key | Anonymous access (lower limit) | | `LLM_API_KEY` | No | LLM API key | None (fallback to Sampling) | | `LLM_BASE_URL` | No | LLM endpoint URL | None | | `LLM_MODEL` | No | LLM model name | None | | `LLM_API_FORMAT` | No | `openai` or `anthropic` | Automatically identified | **Passing method**: 1. MCP client `env` field (standard method) 2. `.env` file (server reads during startup, fallback) ## 📋 Usage Examples ### Built-in Tool Call Example ``` Task: "Calculate 25 * 4 + sqrt(81) and then convert 500 grams to pounds" ``` Agent will automatically: 1. Call `calculator` to calculate `25 * 4 + sqrt(81) = 109` 2. Call `unit_convert` to convert `500 grams = 1.10 pounds` 3. Return the complete reasoning process and final answer ### Search Task Example ``` Task: "Search for the latest AI agent frameworks and summarize the top 3" ``` Agent will call `anysearch_search` to get search results and then reason and summarize. ### Batch Search Example ``` Task: "Search for 'React vs Vue' and 'TypeScript trends 2025' in parallel" ``` Agent will call `anysearch_batch_search` to initiate multiple queries simultaneously. ## 🏗️ Project Structure ``` mini-agent-mcp/ ├── LICENSE # Apache-2.0 license ├── README.md # Project documentation ├── .env.example # Environment variable template ├── package.json # NPM package configuration ├── tsconfig.json # TypeScript configuration ├── assets/ │ └── icon.png # Project icon (512x512) ├── src/ │ ├── index.ts # MCP server entry (includes .env loading + retries) │ ├── tools/ │ │ ├── types.ts # Tool type definitions │ │ ├── registry.ts # Tool registry │ │ ├── calculator.ts # Math calculator │ │ ├── text.ts # Text tools │ │ ├── converter.ts # Unit conversion │ │ ├── datetime.ts # Date and time │ │ ├── random.ts # Random generation │ │ ├── anysearch-client.ts # AnySearch MCP client encapsulation │ │ └── anysearch.ts # AnySearch tool dynamic packaging │ └── agent/ │ ├── llm.ts # LLM communication layer (sampling + HTTP + multi-provider) │ ├── react.ts # ReAct reasoning loop │ └── index.ts # Agent tool definition └── dist/ # Compilation output ``` ## 🔐 Security Notes - No local data storage - API Key passed through environment variables, not written to code or logs - Uses MCP standard protocol communication - Deployable on Alibaba Cloud Function Compute MicroVM sandbox isolated environment - SSE access address is a sensitive exclusive information, please do not leak ## ⚠️ Usage Limitations - Free deployable service has call quota limitations (HTTP 429 returned when exceeded) - Anonymous AnySearch access has rate limitations (recommended to configure API Key) - Agent single task up to 8 tool call steps - Tool call timeout 60 seconds, LLM reasoning timeout 120 seconds - Tool failure automatically retries 3 times (exponential backoff) ## 📄 License [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) © 2026 Microbiosis This project integrates AnySearch (Apache-2.0 license). ## 🤝 Contribution Welcome to submit issues and PRs: https://github.com/Microbiosis/mini-agent-mcp/issues Fork → Modify → Submit request. ## 🔗 Related Links - [ModelScope MCP Platform](https://modelscope.cn/mcp) - [AnySearch Documentation](https://anysearch.com/docs) - [MCP Protocol Specification](https://modelcontextprotocol.io) - [GitHub Repository](https://github.com/Microbiosis/mini-agent-mcp)