mirrors/gpt4free
1
Fork 0
mirror of https://github.com/xtekky/gpt4free.git synced 2025-12-06 02:30:41 -08:00
Code Issues Projects Releases Packages Wiki Activity

Remove MCP usage guide and README files; update logging in API to use print for most wanted IPs; enhance WebSearchTool to support region parameter for search queries.

Browse source
This commit is contained in:
hlohaus 2025-11-01 20:34:47 +01:00
parent 01d194ff4b
commit 5276e2d6d0
4 changed files with 11 additions and 759 deletions
Download patch file Download diff file Expand all files Collapse all files

440
docs/mcp-usage-guide.md
View file

@ -1,440 +0,0 @@
# gpt4free MCP Server - Complete Usage Guide
## Table of Contents
- [Introduction](#introduction)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Available Tools](#available-tools)
- [Integration Examples](#integration-examples)
- [Troubleshooting](#troubleshooting)
## Introduction
The gpt4free MCP (Model Context Protocol) server enables AI assistants like Claude to access powerful capabilities:
- **Web Search**: Real-time web search using DuckDuckGo
- **Web Scraping**: Extract and clean text content from any web page
- **Image Generation**: Create images from text descriptions using various AI models
## Quick Start
### 1. Installation
Make sure gpt4free is installed with all dependencies:
```bash
# Install with all features
pip install -U g4f[all]
# Or install from source
git clone https://github.com/xtekky/gpt4free.git
cd gpt4free
pip install -e .
```
### 2. Start the MCP Server
**Stdio Mode (Default):**
```bash
# Using g4f command
g4f mcp
# Or using Python module
python -m g4f.mcp
# With debug logging
g4f mcp --debug
```
The server will:
- Listen on stdin for JSON-RPC requests
- Write responses to stdout
- Write debug/error messages to stderr
**HTTP Mode:**
```bash
# Start HTTP server on default port 8765
g4f mcp --http
# Custom port
g4f mcp --http --port 3000
# Custom host and port
g4f mcp --http --host 127.0.0.1 --port 8765
```
The HTTP server provides:
- `POST http://localhost:8765/mcp` - JSON-RPC endpoint
- `GET http://localhost:8765/health` - Health check endpoint
HTTP mode is useful for:
- Web-based integrations
- Testing with HTTP clients
- Remote access
- Debugging with tools like curl or Postman
### 3. Test the Server
**Stdio Mode:**
```bash
# Send a test request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python -m g4f.mcp
```
Expected output:
```json
{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05", "serverInfo": {...}}}
```
**HTTP Mode:**
```bash
# Start server
g4f mcp --http --port 8765
# In another terminal, test with curl
curl -X POST http://localhost:8765/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
# Health check
curl http://localhost:8765/health
```
## Configuration
### Claude Desktop
1. Locate your config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
2. Add the MCP server:
```json
{
"mcpServers": {
"gpt4free": {
"command": "python",
"args": ["-m", "g4f.mcp"],
"description": "gpt4free MCP server with web search, scraping, and image generation"
}
}
}
```
3. Restart Claude Desktop
4. Verify in Claude: Ask "What tools do you have access to?" and you should see the gpt4free tools listed.
### VS Code with Cline Extension
Add to your Cline MCP settings:
```json
{
"mcpServers": {
"gpt4free": {
"command": "python",
"args": ["-m", "g4f.mcp"],
"disabled": false
}
}
}
```
### Other MCP Clients
Any MCP-compatible client can use the server. The command is:
```bash
python -m g4f.mcp
```
## Available Tools
### 1. web_search
Search the web for current information.
**Parameters:**
- `query` (string, required): Search query
- `max_results` (integer, optional): Maximum results to return (default: 5)
**Example Request:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "web_search",
"arguments": {
"query": "latest Python 3.12 features",
"max_results": 5
}
}
}
```
**Example Usage in Claude:**
> "Search the web for the latest Python 3.12 features"
### 2. web_scrape
Extract text content from web pages.
**Parameters:**
- `url` (string, required): URL to scrape
- `max_words` (integer, optional): Maximum words to extract (default: 1000)
**Example Request:**
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "web_scrape",
"arguments": {
"url": "https://python.org",
"max_words": 500
}
}
}
```
**Example Usage in Claude:**
> "Scrape the content from https://python.org and summarize it"
### 3. image_generation
Generate images from text descriptions.
**Parameters:**
- `prompt` (string, required): Image description
- `model` (string, optional): Image model (default: "flux")
- `width` (integer, optional): Width in pixels (default: 1024)
- `height` (integer, optional): Height in pixels (default: 1024)
**Example Request:**
```json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "image_generation",
"arguments": {
"prompt": "A serene mountain landscape at sunset",
"width": 1024,
"height": 1024
}
}
}
```
**Example Usage in Claude:**
> "Generate an image of a serene mountain landscape at sunset"
## Integration Examples
### Python Script
```python
import asyncio
import json
from g4f.mcp.server import MCPServer, MCPRequest
async def search_web(query: str):
server = MCPServer()
request = MCPRequest(
jsonrpc="2.0",
id=1,
method="tools/call",
params={
"name": "web_search",
"arguments": {"query": query}
}
)
response = await server.handle_request(request)
return response.result
# Run it
result = asyncio.run(search_web("Python tutorials"))
print(result)
```
### Command Line Testing
```bash
# Test initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | g4f mcp
# Test list tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | g4f mcp
# Test web search
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"web_search","arguments":{"query":"test"}}}' | g4f mcp
```
### Using with Shell Scripts
```bash
#!/bin/bash
# search.sh - Simple web search wrapper
query="$1"
request=$(cat <<EOF
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"web_search","arguments":{"query":"$query"}}}
EOF
)
echo "$request" | python -m g4f.mcp | jq '.result.content[0].text | fromjson'
```
## Troubleshooting
### Server Won't Start
**Problem**: Server exits immediately or shows import errors
**Solution**:
```bash
# Install all dependencies
pip install -r requirements.txt
# Or install with all extras
pip install -U g4f[all]
```
### Tools Return Errors
**Problem**: Tools return error messages about missing packages
**Solution**: Install specific dependencies:
```bash
# For web search
pip install ddgs beautifulsoup4
# For web scraping
pip install aiohttp beautifulsoup4
# For image generation
pip install pillow
```
### Network Errors
**Problem**: Tools fail with connection errors
**Solution**:
- Check internet connectivity
- Some providers may be rate-limited
- Try different providers for image generation
- Check firewall settings
### Claude Desktop Not Finding Server
**Problem**: Claude doesn't show gpt4free tools
**Solution**:
1. Verify config file location and syntax
2. Check that Python is in PATH
3. Try absolute path to Python:
```json
{
"mcpServers": {
"gpt4free": {
"command": "/usr/bin/python3",
"args": ["-m", "g4f.mcp"]
}
}
}
```
4. Restart Claude Desktop completely
5. Check Claude logs for errors
### Debug Mode
Enable debug output:
```bash
# Redirect stderr to see debug messages
g4f mcp 2> mcp_debug.log
# Run with verbose output
g4f mcp --debug 2>&1 | tee mcp_output.log
```
### Verify Installation
Run the test script:
```bash
python etc/testing/test_mcp_server.py
```
Or the interactive demo:
```bash
python etc/testing/test_mcp_interactive.py
```
## Protocol Details
The MCP server implements JSON-RPC 2.0 over stdio transport.
**Supported Methods:**
- `initialize` - Initialize the connection
- `tools/list` - List all available tools
- `tools/call` - Execute a tool
- `ping` - Health check
**Message Format:**
- Requests: One JSON object per line on stdin
- Responses: One JSON object per line on stdout
- Logs: Messages on stderr
## Advanced Usage
### Custom Tool Development
To add custom tools, see `g4f/mcp/tools.py`:
```python
from g4f.mcp.tools import MCPTool
class MyCustomTool(MCPTool):
@property
def description(self) -> str:
return "My custom tool description"
@property
def input_schema(self) -> Dict[str, Any]:
return {
"type": "object",
"properties": {
"param1": {"type": "string", "description": "..."}
},
"required": ["param1"]
}
async def execute(self, arguments: Dict[str, Any]) -> Any:
# Your implementation
pass
```
Register in `g4f/mcp/server.py`:
```python
self.tools['my_tool'] = MyCustomTool()
```
## Support
- Documentation: [g4f/mcp/README.md](README.md)
- Issues: https://github.com/xtekky/gpt4free/issues
- MCP Specification: https://modelcontextprotocol.io/
## License
Part of the gpt4free project, licensed under GNU General Public License v3.0.

2
g4f/api/__init__.py
View file

@ -456,7 +456,7 @@ class Api:
else: else:
most_wanted[x_forwarded_for] = 1 most_wanted[x_forwarded_for] = 1
sorted_most_wanted = dict(sorted(most_wanted.items(), key=lambda item: item[1], reverse=True)) sorted_most_wanted = dict(sorted(most_wanted.items(), key=lambda item: item[1], reverse=True))
debug.log(f"Most wanted IPs: {sorted_most_wanted}") print(f"Most wanted IPs: {json.dumps(sorted_most_wanted, indent=2)}")
if is_most_wanted: if is_most_wanted:
return ErrorResponse.from_message("You are most wanted! Please wait before making another request.", status_code=HTTP_429_TOO_MANY_REQUESTS) return ErrorResponse.from_message("You are most wanted! Please wait before making another request.", status_code=HTTP_429_TOO_MANY_REQUESTS)
if provider is not None and provider not in Provider.__map__: if provider is not None and provider not in Provider.__map__:

316
g4f/mcp/README.md
View file

@ -1,316 +0,0 @@
# gpt4free MCP Server
A Model Context Protocol (MCP) server implementation for gpt4free that provides AI assistants with access to web search, scraping, and image generation capabilities.
## Overview
The gpt4free MCP server exposes three main tools:
1. **Web Search** - Search the web using DuckDuckGo
2. **Web Scraping** - Extract and clean text content from web pages
3. **Image Generation** - Generate images from text prompts using various AI providers
## Installation
The MCP server is included with gpt4free. No additional installation is required beyond the base gpt4free package.
```bash
pip install -e .
```
## Usage
### Running the MCP Server
**Stdio Mode (Default)**
Start the MCP server using:
```bash
python -m g4f.mcp
```
Or using the g4f command:
```bash
g4f mcp
```
The server communicates over stdin/stdout using JSON-RPC 2.0 protocol.
**HTTP Mode**
Start the MCP server with HTTP transport:
```bash
g4f mcp --http --port 8765
```
This starts an HTTP server with the following endpoints:
- `POST http://localhost:8765/mcp` - MCP JSON-RPC endpoint
- `GET http://localhost:8765/health` - Health check endpoint
HTTP mode is useful for:
- Web-based integrations
- Testing with curl or HTTP clients
- Remote access (configure host with `--host`)
Options:
- `--http`: Enable HTTP transport instead of stdio
- `--host HOST`: Host to bind to (default: 0.0.0.0)
- `--port PORT`: Port to bind to (default: 8765)
### Configuration for AI Assistants
**For Claude Desktop (Stdio)** - `claude_desktop_config.json`:
```json
{
"mcpServers": {
"gpt4free": {
"command": "python",
"args": ["-m", "g4f.mcp"]
}
}
}
```
**For HTTP-based clients**:
Make POST requests to `http://localhost:8765/mcp` with JSON-RPC payloads.
Example with curl:
```bash
curl -X POST http://localhost:8765/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
**For VS Code with Cline**:
```json
{
"mcpServers": {
"gpt4free": {
"command": "python",
"args": ["-m", "g4f.mcp"],
"disabled": false
}
}
}
```
## Available Tools
### web_search
Search the web for information.
**Parameters:**
- `query` (string, required): The search query
- `max_results` (integer, optional): Maximum number of results (default: 5)
**Example:**
```json
{
"name": "web_search",
"arguments": {
"query": "latest AI developments 2024",
"max_results": 5
}
}
```
### web_scrape
Scrape and extract text content from a web page.
**Parameters:**
- `url` (string, required): The URL to scrape
- `max_words` (integer, optional): Maximum words to extract (default: 1000)
**Example:**
```json
{
"name": "web_scrape",
"arguments": {
"url": "https://example.com/article",
"max_words": 1000
}
}
```
### image_generation
Generate images from text prompts.
**Parameters:**
- `prompt` (string, required): Description of the image to generate
- `model` (string, optional): Image model to use (default: "flux")
- `width` (integer, optional): Image width in pixels (default: 1024)
- `height` (integer, optional): Image height in pixels (default: 1024)
**Example:**
```json
{
"name": "image_generation",
"arguments": {
"prompt": "A serene mountain landscape at sunset",
"width": 1024,
"height": 1024
}
}
```
## Protocol Details
The MCP server implements the Model Context Protocol using JSON-RPC 2.0 over stdio transport.
### Supported Methods
- `initialize` - Initialize connection with the server
- `tools/list` - List all available tools
- `tools/call` - Execute a tool with given arguments
- `ping` - Health check
### Example Request/Response
**Request:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "web_search",
"arguments": {
"query": "Python programming tutorials",
"max_results": 3
}
}
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"query\": \"Python programming tutorials\", \"results\": [...], \"count\": 3}"
}
]
}
}
```
## Requirements
The MCP server requires the following dependencies (included in gpt4free):
- `aiohttp` - For async HTTP requests
- `beautifulsoup4` - For web scraping
- `ddgs` - For web search
These are automatically installed with:
```bash
pip install -r requirements.txt
```
## Error Handling
The server returns standard JSON-RPC error responses:
- `-32601`: Method not found
- `-32602`: Invalid parameters
- `-32603`: Internal error
Errors specific to tools are returned in the result object with an `error` field.
## Development
### Project Structure
```
g4f/mcp/
├── __init__.py # Package initialization
├── __main__.py # CLI entry point
├── server.py # MCP server implementation
├── tools.py # Tool implementations
└── README.md # This file
```
### Adding New Tools
To add a new tool:
1. Create a new class inheriting from `MCPTool` in `tools.py`
2. Implement the required properties and methods
3. Register the tool in `MCPServer.__init__()` in `server.py`
Example:
```python
class MyNewTool(MCPTool):
@property
def description(self) -> str:
return "Description of what the tool does"
@property
def input_schema(self) -> Dict[str, Any]:
return {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "Parameter description"
}
},
"required": ["param1"]
}
async def execute(self, arguments: Dict[str, Any]) -> Any:
# Implementation
pass
```
## Troubleshooting
### Server Won't Start
Make sure all dependencies are installed:
```bash
pip install -r requirements.txt
```
### Tools Return Errors
Check that:
- Network connectivity is available for web search and scraping
- URLs are valid and accessible
- Image generation providers are not rate-limited
### Debug Mode
The server writes diagnostic information to stderr. To see debug output:
```bash
python -m g4f.mcp 2> debug.log
```
## License
This MCP server is part of the gpt4free project and is licensed under the GNU General Public License v3.0.
## Contributing
Contributions are welcome! Please see the main gpt4free repository for contribution guidelines.
## Related Links
- [gpt4free Repository](https://github.com/xtekky/gpt4free)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [MCP Documentation](https://modelcontextprotocol.io/docs)

12
g4f/mcp/tools.py
View file

@ -61,6 +61,10 @@ class WebSearchTool(MCPTool):
"type": "integer", "type": "integer",
"description": "Maximum number of results to return (default: 5)", "description": "Maximum number of results to return (default: 5)",
"default": 5 "default": 5
},
"region": {
"type": "string",
"description": "Search region (default: en-us)"
} }
}, },
"required": ["query"] "required": ["query"]
@ -76,6 +80,7 @@ class WebSearchTool(MCPTool):
query = arguments.get("query", "") query = arguments.get("query", "")
max_results = arguments.get("max_results", 5) max_results = arguments.get("max_results", 5)
region = arguments.get("region", "en-us")
if not query: if not query:
return { return {
@ -88,7 +93,9 @@ class WebSearchTool(MCPTool):
search_results = await anext(CachedSearch.create_async_generator( search_results = await anext(CachedSearch.create_async_generator(
"", "",
[], [],
prompt=query prompt=query,
max_results=max_results,
region=region
)) ))
return { return {
@ -232,7 +239,8 @@ class ImageGenerationTool(MCPTool):
model=model, model=model,
prompt=prompt, prompt=prompt,
width=width, width=width,
height=height height=height,
response_format="url"
) )
# Get the image data with proper validation # Get the image data with proper validation