|
| 1 | +# ms-agent × nanobot Integration |
| 2 | + |
| 3 | +This directory contains everything needed to use ms-agent's 14 MCP capabilities |
| 4 | +from within nanobot. |
| 5 | + |
| 6 | +## Prerequisites |
| 7 | + |
| 8 | +1. **ms-agent** installed (or available on `PYTHONPATH`) |
| 9 | +2. **nanobot** installed (`pip install nanobot` or dev install) |
| 10 | +3. **mcp** package installed (`pip install mcp`) |
| 11 | +4. API keys configured in a `.env` file (see [Environment & API Keys](#environment--api-keys)) |
| 12 | + |
| 13 | +## Quick Start |
| 14 | + |
| 15 | +### Step 1: Verify ms-agent capabilities |
| 16 | + |
| 17 | +```bash |
| 18 | +cd /path/to/ms-agent |
| 19 | +python3 -m ms_agent.capabilities.mcp_server --check |
| 20 | +``` |
| 21 | + |
| 22 | +Expected output: JSON listing all 14 capabilities. |
| 23 | + |
| 24 | +### Step 2: Install the ms-agent skill into nanobot's workspace |
| 25 | + |
| 26 | +```bash |
| 27 | +./install_skill.sh |
| 28 | +``` |
| 29 | + |
| 30 | +This copies the `ms-agent-skills/` directory into nanobot's workspace skills |
| 31 | +directory so that nanobot's context builder can load it. |
| 32 | + |
| 33 | +### Step 3: Configure nanobot |
| 34 | + |
| 35 | +```bash |
| 36 | +# Option A: Use this demo config directly |
| 37 | +nanobot agent -c examples/nanobot_integration/config.json |
| 38 | + |
| 39 | +# Option B: Merge into your existing ~/.nanobot/config.json |
| 40 | +# Add the mcpServers block from config.json |
| 41 | +``` |
| 42 | + |
| 43 | +### Step 4: Test it |
| 44 | + |
| 45 | +```bash |
| 46 | +# Interactive mode |
| 47 | +nanobot agent -c examples/nanobot_integration/config.json |
| 48 | + |
| 49 | +# Or automated MCP test (no nanobot needed) |
| 50 | +python3 test_mcp_tools.py |
| 51 | +python3 test_mcp_tools.py --list # List tools only |
| 52 | +python3 test_mcp_tools.py --test ws # Test web search only |
| 53 | +``` |
| 54 | + |
| 55 | +## How It Works |
| 56 | + |
| 57 | +``` |
| 58 | +┌──────────────────────────────────────────────────────────┐ |
| 59 | +│ nanobot │ |
| 60 | +│ ┌──────────────────┐ ┌─────────────────────────────┐ │ |
| 61 | +│ │ AgentLoop │ │ ToolRegistry │ │ |
| 62 | +│ │ (ReAct pattern) │───▶│ ├── read_file, exec, ... │ │ |
| 63 | +│ │ │ │ └── mcp_ms-agent_* ◄──┐ │ │ |
| 64 | +│ └──────────────────┘ └─────────────────────┼───┘ │ |
| 65 | +│ │ │ |
| 66 | +│ ┌──────────────────┐ │ │ |
| 67 | +│ │ ContextBuilder │ │ │ |
| 68 | +│ │ ├── SOUL.md │ stdio │ │ |
| 69 | +│ │ ├── Skills ◄─────┼── ms-agent SKILL.md │ │ |
| 70 | +│ │ └── Memory │ │ │ |
| 71 | +│ └──────────────────┘ │ │ |
| 72 | +└─────────────────────────────────────────────────┼──────┘ |
| 73 | + │ |
| 74 | + ▼ |
| 75 | +┌──────────────────────────────────────────────────────────┐ |
| 76 | +│ ms-agent MCP Server (python -m ms_agent.capabilities. │ |
| 77 | +│ mcp_server) │ |
| 78 | +│ ┌────────────────────────────────────────────────────┐ │ |
| 79 | +│ │ CapabilityRegistry (14 tools) │ │ |
| 80 | +│ │ ├── web_search (arxiv/exa/serpapi) │ │ |
| 81 | +│ │ ├── delegate_task (sync agent) │ │ |
| 82 | +│ │ ├── submit_agent_task (async agent) │ │ |
| 83 | +│ │ ├── check/get/cancel_agent_task │ │ |
| 84 | +│ │ ├── submit_research_task (async research) │ │ |
| 85 | +│ │ ├── check/get_research_progress/report │ │ |
| 86 | +│ │ ├── lsp_check_directory (code validation) │ │ |
| 87 | +│ │ ├── lsp_update_and_check │ │ |
| 88 | +│ │ ├── replace_file_contents (concurrent-safe edit) │ │ |
| 89 | +│ │ └── replace_file_lines │ │ |
| 90 | +│ └────────────────────────────────────────────────────┘ │ |
| 91 | +└──────────────────────────────────────────────────────────┘ |
| 92 | +``` |
| 93 | + |
| 94 | +### Two Integration Layers |
| 95 | + |
| 96 | +1. **MCP Tools** — nanobot connects to ms-agent's MCP server via stdio. |
| 97 | + All 14 capabilities appear as tools (prefixed `mcp_ms-agent_<name>`). |
| 98 | + The agent can call them directly during the ReAct loop. |
| 99 | + |
| 100 | +2. **Skill Context** — the `ms-agent-skills/SKILL.md` is installed into |
| 101 | + nanobot's workspace. It teaches the agent *when* and *how* to use each |
| 102 | + MCP tool. The skill includes a decision guide and links to detailed |
| 103 | + reference docs for each capability. |
| 104 | + |
| 105 | +## Test Prompts |
| 106 | + |
| 107 | +### Web Search (instant) |
| 108 | + |
| 109 | +> Search arxiv for recent papers on LLM agent frameworks. |
| 110 | +
|
| 111 | +### File Editing (instant) |
| 112 | + |
| 113 | +> Create a file called test_demo.py with a hello world function, then use |
| 114 | +> replace_file_contents to rename the function from hello to greet. |
| 115 | +
|
| 116 | +### LSP Validation (1-5 min) |
| 117 | + |
| 118 | +> Check the code in /path/to/project for TypeScript errors using LSP. |
| 119 | +
|
| 120 | +### Agent Delegation (sync, minutes) |
| 121 | + |
| 122 | +> Use delegate_task to research and compare the top 3 Python async frameworks. |
| 123 | +
|
| 124 | +### Deep Research (async, 20-60 min) |
| 125 | + |
| 126 | +> Research "the current state of AI agent frameworks in 2026" — submit it |
| 127 | +> as a background task and let me know when it's done. |
| 128 | +
|
| 129 | +### Agent Delegation (async) |
| 130 | + |
| 131 | +> Submit an agent task to analyze the architecture of this project and suggest |
| 132 | +> improvements. Check on it periodically and show me the results when done. |
| 133 | +
|
| 134 | +## Environment & API Keys |
| 135 | + |
| 136 | +The MCP server automatically loads a `.env` file on startup, so all |
| 137 | +capabilities (web search, deep research, agent delegation, etc.) and their |
| 138 | +subprocesses can access API keys without any extra configuration. |
| 139 | + |
| 140 | +**Setup:** Create a `.env` file in the ms-agent project root: |
| 141 | + |
| 142 | +```bash |
| 143 | +# LLM provider |
| 144 | +OPENAI_API_KEY=sk-xxx |
| 145 | +OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 |
| 146 | + |
| 147 | +# Search engines (optional, only needed if you use exa/serpapi) |
| 148 | +EXA_API_KEY=xxx |
| 149 | +SERPAPI_API_KEY=xxx |
| 150 | +``` |
| 151 | + |
| 152 | +**How it works:** The server uses `find_dotenv()` to walk up from the current |
| 153 | +directory and find the nearest `.env`. Variables already set in the process |
| 154 | +environment (e.g. via the MCP client `env` block or `export`) are **never** |
| 155 | +overwritten, so you can always override `.env` values per-session. |
| 156 | + |
| 157 | +**Priority** (highest → lowest): |
| 158 | + |
| 159 | +1. MCP client `env` block (in `config.json`) |
| 160 | +2. Shell `export` / system environment |
| 161 | +3. `.env` file |
| 162 | + |
| 163 | +**Explicit path:** If your `.env` is not in an ancestor directory, pass it |
| 164 | +explicitly: |
| 165 | + |
| 166 | +```json |
| 167 | +{ |
| 168 | + "args": ["-m", "ms_agent.capabilities.mcp_server", "--env-file", "/path/to/.env"] |
| 169 | +} |
| 170 | +``` |
| 171 | + |
| 172 | +| Variable | Required by | Notes | |
| 173 | +|----------|-------------|-------| |
| 174 | +| `OPENAI_API_KEY` | deep_research, delegate_task | Any OpenAI-compatible provider | |
| 175 | +| `OPENAI_BASE_URL` | deep_research, delegate_task | Defaults to DashScope if unset in YAML | |
| 176 | +| `EXA_API_KEY` | web_search (exa engine) | Only needed for `engine_type='exa'` | |
| 177 | +| `SERPAPI_API_KEY` | web_search (serpapi engine) | Only needed for `engine_type='serpapi'` | |
| 178 | + |
| 179 | +## MCP Configuration |
| 180 | + |
| 181 | +The key block in `config.json`: |
| 182 | + |
| 183 | +```json |
| 184 | +{ |
| 185 | + "tools": { |
| 186 | + "mcpServers": { |
| 187 | + "ms-agent": { |
| 188 | + "command": "python3", |
| 189 | + "args": ["-m", "ms_agent.capabilities.mcp_server"], |
| 190 | + "env": { |
| 191 | + "PYTHONPATH": "/path/to/ms-agent", |
| 192 | + "MS_AGENT_OUTPUT_DIR": "/path/to/workspace" |
| 193 | + }, |
| 194 | + "toolTimeout": 120, |
| 195 | + "enabledTools": ["*"] |
| 196 | + } |
| 197 | + } |
| 198 | + } |
| 199 | +} |
| 200 | +``` |
| 201 | + |
| 202 | +**Key settings:** |
| 203 | + |
| 204 | +| Field | Description | |
| 205 | +|-------|-------------| |
| 206 | +| `command` + `args` | Launches the MCP server via stdio | |
| 207 | +| `env.PYTHONPATH` | Ensures ms-agent is importable | |
| 208 | +| `env.MS_AGENT_OUTPUT_DIR` | Workspace root for file operations | |
| 209 | +| `toolTimeout` | Seconds before tool call times out (120s recommended for delegate_task) | |
| 210 | +| `enabledTools` | `["*"]` for all tools, or list specific ones | |
| 211 | + |
| 212 | +### Selective Tool Enablement |
| 213 | + |
| 214 | +If you only need specific capabilities: |
| 215 | + |
| 216 | +```json |
| 217 | +{ |
| 218 | + "enabledTools": [ |
| 219 | + "web_search", |
| 220 | + "replace_file_contents", |
| 221 | + "replace_file_lines", |
| 222 | + "submit_research_task", |
| 223 | + "check_research_progress", |
| 224 | + "get_research_report" |
| 225 | + ] |
| 226 | +} |
| 227 | +``` |
| 228 | + |
| 229 | +## Files |
| 230 | + |
| 231 | +| File | Purpose | |
| 232 | +|------|---------| |
| 233 | +| `config.json` | nanobot config with ms-agent MCP server | |
| 234 | +| `install_skill.sh` | Copies ms-agent skill to nanobot workspace | |
| 235 | +| `test_mcp_tools.py` | Standalone test that exercises MCP tools directly | |
0 commit comments