From 5276e2d6d092aa6578f38f7da35ce768cbca29f0 Mon Sep 17 00:00:00 2001 From: hlohaus <983577+hlohaus@users.noreply.github.com> Date: Sat, 1 Nov 2025 20:34:47 +0100 Subject: [PATCH] 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. --- docs/mcp-usage-guide.md | 440 ---------------------------------------- g4f/api/__init__.py | 2 +- g4f/mcp/README.md | 316 ----------------------------- g4f/mcp/tools.py | 12 +- 4 files changed, 11 insertions(+), 759 deletions(-) delete mode 100644 docs/mcp-usage-guide.md delete mode 100644 g4f/mcp/README.md diff --git a/docs/mcp-usage-guide.md b/docs/mcp-usage-guide.md deleted file mode 100644 index f2a43f73..00000000 --- a/docs/mcp-usage-guide.md +++ /dev/null @@ -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 < 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. diff --git a/g4f/api/__init__.py b/g4f/api/__init__.py index 7380a5c6..2fd83b6b 100644 --- a/g4f/api/__init__.py +++ b/g4f/api/__init__.py @@ -456,7 +456,7 @@ class Api: else: most_wanted[x_forwarded_for] = 1 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: 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__: diff --git a/g4f/mcp/README.md b/g4f/mcp/README.md deleted file mode 100644 index 1da85e3c..00000000 --- a/g4f/mcp/README.md +++ /dev/null @@ -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) diff --git a/g4f/mcp/tools.py b/g4f/mcp/tools.py index 1f82d631..ebc6d875 100644 --- a/g4f/mcp/tools.py +++ b/g4f/mcp/tools.py @@ -61,6 +61,10 @@ class WebSearchTool(MCPTool): "type": "integer", "description": "Maximum number of results to return (default: 5)", "default": 5 + }, + "region": { + "type": "string", + "description": "Search region (default: en-us)" } }, "required": ["query"] @@ -76,6 +80,7 @@ class WebSearchTool(MCPTool): query = arguments.get("query", "") max_results = arguments.get("max_results", 5) + region = arguments.get("region", "en-us") if not query: return { @@ -88,7 +93,9 @@ class WebSearchTool(MCPTool): search_results = await anext(CachedSearch.create_async_generator( "", [], - prompt=query + prompt=query, + max_results=max_results, + region=region )) return { @@ -232,7 +239,8 @@ class ImageGenerationTool(MCPTool): model=model, prompt=prompt, width=width, - height=height + height=height, + response_format="url" ) # Get the image data with proper validation