Content
# MCP Tools Converter
## 📋 Project Overview
MCP Tools Converter is a powerful Python tool designed to automatically discover, connect, and convert tools from Model Context Protocol (MCP) servers into the standard OpenAI Function Calling format. This project helps developers easily integrate functionalities provided by various MCP servers into AI applications that support Function Calling.
## ✨ Key Features
### 🔧 Core Features
- **Automatic Server Discovery**: Automatically load and connect to multiple MCP servers from a configuration file.
- **Intelligent Tool Conversion**: Convert MCP tool formats into OpenAI Function Calling format.
- **Mixed Output Parsing**: Smartly handle mixed logs and JSON outputs returned by the server.
- **Multithreading**: Concurrently process multiple server connections to improve efficiency.
- **Complete Parameter Mapping**: Retain all parameter information and type definitions of the original tools.
- **Format Validation**: Automatically validate the correctness of the generated Function Calling format.
### 🛠️ Supported MCP Server Types
- **Exa AI**: Web search, academic paper retrieval, company research, etc.
- **Google Maps**: Geocoding, place search, route planning, etc.
- **Excel**: Spreadsheet operations, data processing, chart creation, etc.
- **Calculator**: Mathematical expression evaluation.
- **Fetch**: Web content retrieval and parsing.
- **Mindmap**: Convert Markdown to mind maps.
## 📁 Project Structure
```
alone/
├── mcp_tools_getter_final.py # Main program - MCP Tools Getter
├── get_tool.py # Tool conversion module
├── mcp_config.json # MCP server configuration file
├── mcp_tool.json # Generated Function Calling tool registry
├── requirements.txt # Python dependencies
└── README.md # Project documentation
```
## 🚀 Installation and Usage
### Environment Requirements
- Python 3.7+
- Node.js (for running npx commands)
- UV package manager (for running uvx commands)
### Installation Steps
1. **Clone or Download the Project**
```bash
git clone <repository-url>
cd alone
```
2. **Install Python Dependencies**
```bash
pip install -r requirements.txt
```
3. **Configure API Keys**
Edit the `mcp_config.json` file to add your API keys:
```json
{
"mcpServers": {
"exa": {
"env": {
"EXA_API_KEY": "your_exa_api_key_here"
}
},
"google-maps": {
"env": {
"GOOGLE_MAPS_API_KEY": "your_google_maps_api_key_here"
}
}
}
}
```
### Run the Program
```bash
python mcp_tools_getter_final.py
```
The program will automatically:
1. 🔌 Connect to the configured MCP servers.
2. 📡 Retrieve the tool list from each server.
3. 🔄 Convert to Function Calling format.
4. 💾 Save to the `mcp_tool.json` file.
5. ✅ Validate the generated format.
## 📊 Output File
### mcp_tool.json
The generated Function Calling tool registry includes:
```json
{
"function_calling_tools": [
{
"name": "mcp_exa_web_search_exa",
"description": "Search the web using Exa AI...",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query"
}
},
"required": ["query"]
}
}
],
"metadata": {
"format": "OpenAI Function Calling",
"generated_by": "MCP Tools Getter",
"servers": ["exa", "calculator", "google-maps", "excel", "fetch", "mindmap"],
"total_tools": 38
}
}
```
## ⚙️ Configuration Description
### MCP Server Configuration (mcp_config.json)
Each server configuration includes:
- **command**: Startup command (`npx` or `uvx`)
- **args**: Command arguments
- **env**: Environment variables (e.g., API keys)
Example:
```json
{
"mcpServers": {
"server_name": {
"command": "npx",
"args": ["-y", "server-package-name"],
"env": {
"API_KEY": "your_api_key"
}
}
}
}
```
## 🔧 Advanced Features
### Tool Name Prefix
To avoid tool name conflicts, the converter automatically adds a server prefix to each tool:
- Original: `web_search_exa`
- Converted: `mcp_exa_web_search_exa`
### Parameter Type Mapping
Supports complete JSON Schema to Function Calling parameter mapping:
- Basic types: `string`, `number`, `boolean`
- Composite types: `array`, `object`
- Constraints: `enum`, `minimum`, `maximum`, `required`
- Default values and descriptions
### Error Handling
- 🔄 Automatically retries failed server connections.
- 📝 Detailed error logs and diagnostic information.
- ⚠️ Gracefully handles partial server failures.
## 🐛 Troubleshooting
### Common Issues
1. **Server Connection Failed**
- Check network connection.
- Verify that the API keys are correct.
- Ensure that the required npm packages are installed.
2. **Encoding Errors**
- Ensure the system uses UTF-8 encoding.
- Check the encoding settings of PowerShell or terminal.
3. **Permission Issues**
- Run as an administrator.
- Check folder write permissions.
## 🔄 Development and Extension
### Adding New MCP Servers
1. Add server configuration in `mcp_config.json`.
2. Run the program to automatically discover and convert new tools.
3. Check the generated `mcp_tool.json` file.
### Custom Conversion Logic
Modify the conversion functions in `get_tool.py` to accommodate special needs:
- `convert_mcp_to_function_calling()`: Main conversion logic.
- `convert_property()`: Parameter type conversion.
- `validate_function_calling_format()`: Format validation.
## 📈 Performance Optimization
- Use multithreading to concurrently process multiple servers.
- Intelligent output buffering and parsing.
- Optimized JSON handling and validation.
- Memory-efficient handling of large files.
## 🤝 Contribution Guidelines
Contributions in the form of issue reports and feature requests are welcome!
## 📄 License
This project is licensed under the MIT License.
## 🙋♂️ Support
If you encounter issues or need assistance, please:
1. Check the troubleshooting section.
2. Review existing Issues.
3. Create a new Issue to describe your problem.
---
**Note**: Please ensure you have valid keys and permissions for the configured API services before use.
