README.md•5.3 kB
# MCP Dynamic Tools
**Drop Python files, get MCP tools instantly.**
A dynamic MCP server that automatically discovers Python files in a directory and exposes them as tools to any MCP-compatible AI client. Created through collaboration between Ben Wilson and Claude (Anthropic).
## How it works
```python
# 1. Write a Python file or have the LLM write one
def invoke(arguments):
"""Generate a secure password
Parameters:
- length: Length of password (default: 12)
- include_symbols: Include special characters (default: true)
"""
import random, string
length = int(arguments.get('length', 12))
chars = string.ascii_letters + string.digits
if arguments.get('include_symbols', 'true').lower() == 'true':
chars += "!@#$%^&*"
return ''.join(random.choice(chars) for _ in range(length))
```
```bash
# 2. Save it to your tools directory
echo "# Above code" > tools/password_generator.py
```
```
# 3. AI can now use it immediately (after restart in Claude Desktop)
🤖 "Generate a 16-character password with symbols"
🔧 Tool: password_generator(length="16", include_symbols="true")
📤 Result: "K9#mP2$vR8@nQ3!x"
```
## Quick Start
### 1. Clone and Setup
```bash
git clone https://github.com/your-username/mcp-dynamic-tools
cd mcp-dynamic-tools
```
### 2. Create Tools Directory
```bash
mkdir tools
```
### 3. Configure Your MCP Client
**Claude Desktop** (`~/.config/claude_desktop_config.json`):
```json
{
"mcpServers": {
"mcp-dynamic-tools": {
"command": "python3",
"args": [
"/path/to/mcp-dynamic-tools/src/mcp_dynamic_tools/server.py",
"--tools-dir",
"/path/to/tools"
]
}
}
}
```
### 4. Create Your First Tool
```python
# tools/hello.py
def invoke(arguments):
"""Say hello to someone
Parameters:
- name: The person to greet
"""
name = arguments.get('name', 'World')
return f"Hello, {name}! 👋"
```
### 5. Restart Your MCP Client
Your `hello` tool is now available to any AI using your MCP client!
## How It Works
1. **File Discovery**: Server monitors your tools directory
2. **Code Analysis**: Validates Python files have `invoke(arguments)` function
3. **Schema Extraction**: Parses docstrings for parameter definitions
4. **MCP Integration**: Exposes tools via standard MCP protocol
5. **Error Handling**: Provides detailed feedback for debugging
## Writing Tools
### Function Signature
Every tool must have this exact signature:
```python
def invoke(arguments):
# Your tool logic here
return result
```
### Documentation Format
```python
def invoke(arguments):
"""Brief description of what the tool does
Parameters:
- param_name: Description of the parameter
- another_param: Description with (default: value)
"""
```
### Example Tools
**Text Processor**:
```python
def invoke(arguments):
"""Transform text in various ways
Parameters:
- text: The text to transform
- operation: Type of transformation (uppercase, lowercase, reverse)
"""
text = arguments.get('text', '')
operation = arguments.get('operation', 'uppercase')
if operation == 'uppercase':
return text.upper()
elif operation == 'lowercase':
return text.lower()
elif operation == 'reverse':
return text[::-1]
else:
return f"Unknown operation: {operation}"
```
**API Caller**:
```python
def invoke(arguments):
"""Fetch data from a REST API
Parameters:
- url: The API endpoint to call
- method: HTTP method (default: GET)
"""
import urllib.request
import json
url = arguments.get('url')
method = arguments.get('method', 'GET')
if not url:
return "Error: URL is required"
try:
with urllib.request.urlopen(url) as response:
return json.loads(response.read())
except Exception as e:
return f"Error: {str(e)}"
```
## Robust Error Handling
The server provides detailed error messages to help you debug:
- **Syntax Errors**: Shows line numbers and specific issues
- **Import Errors**: Reports missing dependencies
- **Function Signature**: Validates `invoke(arguments)` signature
- **Runtime Errors**: Captures and reports execution problems
## Known Limitations
### Claude Desktop 0.9.2
Claude Desktop currently doesn't support dynamic tool discovery ([see discussion](https://github.com/orgs/modelcontextprotocol/discussions/76)). This means:
- ✅ **Tools work perfectly** once discovered
- ❌ **Restart required** when adding new tools
- 🔄 **Future support planned** - our server is ready with `listChanged: true`
**Workaround**: Restart Claude Desktop after adding new tools.
### Tool Naming in Claude Desktop
Tools appear with server prefix: `local__mcp-dynamic-tools__your_tool_name`
## Contributing
This project was created through human-AI collaboration. We welcome contributions!
1. Fork the repository
2. Create your feature branch
3. Add tests for new functionality
4. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Acknowledgments
- **Ben Vierck** - Architecture and development
- **Claude (Anthropic)** - Co-development and testing
- **MCP Community** - Protocol development and feedback