Skip to content

Commit 1a6f487

Browse files
veithlyveithly
authored
Merge pull request #129 from veithly/docs/fix-mcp
Enhance MCP Tool Documentation and Configuration
2 parents 5339cbb + eaeab4a commit 1a6f487

File tree

3 files changed

+481
-135
lines changed

3 files changed

+481
-135
lines changed

‎doc/agent.md‎

Lines changed: 123 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,9 @@ In the `initialize` method, we set up and load all necessary tools.
5252

5353
`MCPTool` is designed to be **transport-agnostic**. You can configure it to connect to any MCP server using **stdio**, **HTTP (SSE)**, or **WebSocket**.
5454

55-
**1. Stdio-based Transport (npx, python, etc.)**
55+
**1. Stdio-based Transport (Recommended)**
56+
57+
**Stdio tools** are the recommended approach for most MCP integrations. They run as subprocesses and communicate via stdin/stdout, with automatic lifecycle management by SpoonOS.
5658

5759
Use the `command` field to execute local command-line tools. The tool's `name` should directly match the MCP tool's name.
5860

@@ -63,7 +65,8 @@ tavily_tool = MCPTool(
6365
mcp_config={
6466
"command": "npx",
6567
"args": ["--yes", "tavily-mcp"],
66-
"env": {"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY")}
68+
"env": {"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY")},
69+
"transport": "stdio"
6770
}
6871
)
6972
```
@@ -184,8 +187,122 @@ if __name__ == "__main__":
184187

185188
---
186189

187-
## 4. Next Steps
190+
## 4. MCP Tool Best Practices
191+
192+
### Choosing the Right Transport
193+
194+
| Transport | Use Case | Pros | Cons |
195+
|-----------|----------|------|------|
196+
| **Stdio** | Most MCP tools (Tavily, GitHub, Brave) | Auto-managed, reliable, up-to-date | Limited to command-line tools |
197+
| **SSE** | Custom/in-development tools | Flexible, supports custom servers | Manual server management |
198+
| **WebSocket** | Real-time bidirectional communication | Low latency, persistent connection | Complex setup, manual management |
199+
200+
### Configuration Best Practices
201+
202+
1. **Prefer Stdio for standard tools**: Use stdio transport for well-established MCP tools
203+
2. **Environment variable management**: Store API keys in environment variables, not in code
204+
3. **Error handling**: Set appropriate timeouts and retry attempts
205+
4. **Tool naming**: Use descriptive names that match the tool's functionality
206+
5. **Resource management**: Limit concurrent tool usage to avoid rate limits
207+
208+
### Example: Production-Ready Tool Configuration
209+
210+
```python
211+
async def initialize(self):
212+
"""Initialize agent with production-ready tool configuration"""
213+
214+
# Validate required environment variables
215+
required_env_vars = ["TAVILY_API_KEY", "GITHUB_TOKEN", "OKX_API_KEY"]
216+
for var in required_env_vars:
217+
if not os.getenv(var):
218+
raise ValueError(f"Required environment variable {var} is not set")
219+
220+
# Configure tools with proper error handling
221+
tools = []
222+
223+
# Stdio-based tools (recommended)
224+
try:
225+
tavily_tool = MCPTool(
226+
name="tavily-search",
227+
description="Web search using Tavily API",
228+
mcp_config={
229+
"command": "npx",
230+
"args": ["-y", "tavily-mcp"],
231+
"env": {"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY")},
232+
"transport": "stdio",
233+
"timeout": 30,
234+
"retry_attempts": 3
235+
}
236+
)
237+
tools.append(tavily_tool)
238+
except Exception as e:
239+
logging.warning(f"Failed to initialize Tavily tool: {e}")
240+
241+
# Built-in tools
242+
try:
243+
crypto_tool = CryptoPowerDataCEXTool()
244+
tools.append(crypto_tool)
245+
except Exception as e:
246+
logging.warning(f"Failed to initialize crypto tool: {e}")
247+
248+
self.avaliable_tools = ToolManager(tools)
249+
logging.info(f"Initialized {len(tools)} tools successfully")
250+
```
251+
252+
### Troubleshooting Common Issues
253+
254+
#### Stdio Tool Issues
255+
256+
**Problem**: Tool command not found
257+
```bash
258+
Error: Command 'npx' not found
259+
```
260+
**Solution**: Ensure Node.js and npm are installed and in PATH
261+
262+
**Problem**: Environment variables not loaded
263+
```bash
264+
Error: TAVILY_API_KEY is required
265+
```
266+
**Solution**: Check environment variable configuration in mcp_config
267+
268+
#### SSE Tool Issues
269+
270+
**Problem**: Connection refused
271+
```bash
272+
Error: Connection refused to http://127.0.0.1:8765/sse
273+
```
274+
**Solution**: Ensure the SSE server is running and accessible
275+
276+
**Problem**: Timeout errors
277+
```bash
278+
Error: Request timeout after 30 seconds
279+
```
280+
**Solution**: Increase timeout in mcp_config or check server performance
281+
282+
#### General Debugging
283+
284+
1. **Enable debug logging**:
285+
```python
286+
import logging
287+
logging.basicConfig(level=logging.DEBUG)
288+
```
289+
290+
2. **Check tool availability**:
291+
```python
292+
print(f"Available tools: {list(self.avaliable_tools.tool_map.keys())}")
293+
```
294+
295+
3. **Test tool connectivity**:
296+
```python
297+
# Test individual tool
298+
result = await tool.execute("test_function", {})
299+
```
300+
301+
---
302+
303+
## 5. Next Steps
188304

189-
- **Customize**: Modify the `system_prompt` or add new tools to the `ToolManager`.
190-
- **Explore**: Investigate other built-in toolkits or connect to different MCP services.
191-
- **Advanced Configuration**: For more complex setups, refer to the [Configuration Guide](./configuration.md).
305+
- **Customize**: Modify the `system_prompt` or add new tools to the `ToolManager`
306+
- **Explore**: Investigate other built-in toolkits or connect to different MCP services
307+
- **Advanced Configuration**: For more complex setups, refer to the [Configuration Guide](./configuration.md)
308+
- **MCP Protocol**: Learn more at [MCP Protocol Documentation](https://modelcontextprotocol.io/)

‎doc/configuration.md‎

Lines changed: 173 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -528,7 +528,179 @@ python -c "import json; print('Valid JSON' if json.load(open('config.json')) els
528528

529529
---
530530

531+
---
532+
533+
## 12. 🔌 MCP Tool Integration Guide
534+
535+
SpoonOS supports two main types of MCP (Model Context Protocol) tools for integrating external services and APIs:
536+
537+
### MCP Tool Types Overview
538+
539+
| Tool Type | Config `"type"` | Transport | How to Use/Connect | Example Use Case |
540+
|-------------|-----------------|-------------|-----------------------------------|---------------------------------|
541+
| Stdio MCP | `"mcp"` | `"stdio"` | Auto-managed subprocess | Tavily, GitHub, Brave, etc. |
542+
| SSE MCP | `"mcp"` | `"sse"` | Start your own SSE server | Custom Web3, in-house tools |
543+
| Built-in | `"builtin"` | N/A | Provided by SpoonOS | Crypto tools, price data, etc. |
544+
545+
### Recommended: Stdio MCP Tools
546+
547+
**Stdio tools** are MCP tools that run as a subprocess and communicate with SpoonOS via stdin/stdout. They are the recommended approach for most use cases because:
548+
549+
- No need to run or configure any server manually
550+
- Auto-managed lifecycle by SpoonOS
551+
- Always up to date with latest tool versions
552+
- Automatic restart on failures
553+
554+
#### Stdio Tool Configuration
555+
556+
```json
557+
{
558+
"name": "tavily_search",
559+
"type": "mcp",
560+
"mcp_server": {
561+
"command": "npx",
562+
"args": ["-y", "tavily-mcp"],
563+
"transport": "stdio",
564+
"env": {
565+
"TAVILY_API_KEY": "your-tavily-api-key"
566+
},
567+
"timeout": 30,
568+
"retry_attempts": 3
569+
}
570+
}
571+
```
572+
573+
#### Common Stdio MCP Tools
574+
575+
```json
576+
{
577+
"tools": [
578+
{
579+
"name": "tavily_search",
580+
"type": "mcp",
581+
"mcp_server": {
582+
"command": "npx",
583+
"args": ["-y", "tavily-mcp"],
584+
"transport": "stdio"
585+
}
586+
},
587+
{
588+
"name": "github_tools",
589+
"type": "mcp",
590+
"mcp_server": {
591+
"command": "npx",
592+
"args": ["-y", "@modelcontextprotocol/server-github"],
593+
"transport": "stdio"
594+
}
595+
},
596+
{
597+
"name": "brave_search",
598+
"type": "mcp",
599+
"mcp_server": {
600+
"command": "npx",
601+
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
602+
"transport": "stdio"
603+
}
604+
}
605+
]
606+
}
607+
```
608+
609+
### Advanced: SSE MCP Tools
610+
611+
**SSE tools** are MCP tools that run as separate servers and communicate via Server-Sent Events (SSE). Use these for:
612+
613+
- Custom or in-development integrations
614+
- Tools that need to run independently
615+
- Legacy MCP servers
616+
617+
#### SSE Tool Configuration
618+
619+
```json
620+
{
621+
"name": "my_custom_tool",
622+
"type": "mcp",
623+
"mcp_server": {
624+
"endpoint": "http://127.0.0.1:8765/sse",
625+
"transport": "sse",
626+
"timeout": 30,
627+
"retry_attempts": 3
628+
}
629+
}
630+
```
631+
632+
#### Starting SSE Servers
633+
634+
You must manually start SSE servers before using them:
635+
636+
```bash
637+
# Example: Custom FastMCP server
638+
python my_mcp_server.py
639+
640+
# Example: GitHub MCP server as SSE
641+
npx -y @modelcontextprotocol/server-github --sse
642+
```
643+
644+
### Mixed Tool Configuration Example
645+
646+
You can combine Stdio, SSE, and built-in tools in a single agent:
647+
648+
```json
649+
{
650+
"agents": {
651+
"web3_agent": {
652+
"class": "SpoonReactMCP",
653+
"tools": [
654+
{
655+
"name": "tavily_search",
656+
"type": "mcp",
657+
"mcp_server": {
658+
"command": "npx",
659+
"args": ["-y", "tavily-mcp"],
660+
"transport": "stdio",
661+
"env": {
662+
"TAVILY_API_KEY": "your-tavily-api-key"
663+
}
664+
}
665+
},
666+
{
667+
"name": "my_custom_tool",
668+
"type": "mcp",
669+
"mcp_server": {
670+
"endpoint": "http://127.0.0.1:8765/sse",
671+
"transport": "sse"
672+
}
673+
},
674+
{
675+
"name": "crypto_tools",
676+
"type": "builtin"
677+
}
678+
]
679+
}
680+
}
681+
}
682+
```
683+
684+
### MCP Tool Best Practices
685+
686+
1. **Prefer Stdio MCP tools** for most use cases—no server management, always up to date, auto-restart
687+
2. Use `"sse"` tools only for custom or in-development integrations
688+
3. You can mix Stdio, SSE, and built-in tools in a single agent
689+
4. All tool configuration is managed in `config.json`—no need to modify code for tool integration
690+
5. Use environment variables for API keys and sensitive configuration
691+
6. Set appropriate timeouts and retry attempts for reliability
692+
693+
### MCP Tool Troubleshooting
694+
695+
- **Stdio tool not available**: Check the command and args in your config
696+
- **SSE tool connection failed**: Ensure the server is running and the endpoint is correct
697+
- **Environment variables not loaded**: Verify env vars are set in tool config or system environment
698+
- **Tool timeout issues**: Increase timeout values in mcp_server config
699+
- **Permission errors**: Check file permissions for command executables
700+
701+
---
702+
531703
## Next Steps
532704

533705
- [Agent Development Guide](./agent.md)
534-
- [MCP Mode Usage](./mcp_mode_usage.md)
706+
- [MCP Protocol Documentation](https://modelcontextprotocol.io/)

0 commit comments

Comments
 (0)