Skip to main content
Glama

ConceptNet MCP Server

by infinitnet
README.mdโ€ข13.6 kB
# ConceptNet MCP Server A Model Context Protocol (MCP) server that provides seamless access to the ConceptNet knowledge graph through FastMCP framework. [![CI](https://github.com/infinitnet/conceptnet-mcp/workflows/CI/badge.svg)](https://github.com/infinitnet/conceptnet-mcp/actions/workflows/ci.yml) [![Release](https://github.com/infinitnet/conceptnet-mcp/workflows/Release/badge.svg)](https://github.com/infinitnet/conceptnet-mcp/actions/workflows/release.yml) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![License: GPL-3.0](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) ## Overview ConceptNet MCP provides AI assistants and applications with structured access to ConceptNet's semantic knowledge through four powerful MCP tools: - **Concept Lookup**: Get detailed information about specific concepts - **Concept Query**: Search and filter concepts with advanced criteria - **Related Concepts**: Find concepts connected through semantic relationships - **Concept Relatedness**: Calculate semantic similarity between concepts ## Features - ๐Ÿš€ **FastMCP Integration**: Built on the modern FastMCP framework for optimal performance - ๐Ÿ” **Comprehensive Search**: Advanced querying with language filtering and pagination - ๐ŸŒ **Multi-language Support**: Access ConceptNet's multilingual knowledge base - ๐Ÿ“Š **Semantic Analysis**: Calculate relatedness scores between concepts - ๐Ÿ”„ **Async Operations**: Full async/await support for non-blocking operations - ๐Ÿ“ **Type Safety**: Complete Pydantic v2 type validation and IDE support - ๐Ÿงช **Production Ready**: Error handling, logging, and testing - โšก **Optimized Output Formats**: Choose between minimal (~96% smaller) or comprehensive responses ## Output Formats ConceptNet MCP Server supports two output formats for all tools to optimize performance and reduce token usage: ### Minimal Format (Default - Recommended) - **Size**: ~96% smaller than verbose format - **Optimized**: Designed specifically for LLM consumption - **Content**: Essential data only - concepts, relationships, similarity scores - **Performance**: Faster processing and reduced API costs - **Usage**: Perfect for most AI applications and chat interfaces ### Verbose Format - **Size**: Full ConceptNet response data - **Content**: Complete metadata, statistics, analysis, and original API responses - **Usage**: Detailed analysis, debugging, or when full context is needed - **Backward Compatibility**: Maintains compatibility with existing integrations ### Setting the Format All tools accept a `verbose` parameter: ```json { "name": "concept_lookup", "arguments": { "term": "artificial intelligence", "verbose": false // Default: minimal format } } ``` ```json { "name": "related_concepts", "arguments": { "term": "machine learning", "verbose": true // Full detailed format } } ``` **Examples of size difference:** - Minimal: `{"concept": "dog", "relationships": {"IsA": ["animal", "mammal"]}}` - Verbose: Full ConceptNet response with complete metadata, statistics, timestamps, etc. ## Quick Start ### Installation ```bash # Clone the repository git clone https://github.com/infinitnet/conceptnet-mcp.git cd conceptnet-mcp # Install in development mode pip install -e . ``` ### Running the MCP Server The server supports both **stdio** (for desktop MCP clients) and **HTTP** (for web clients) transport modes: #### Stdio Transport (Default - for desktop MCP clients) ```bash # Start with stdio transport (default) conceptnet-mcp # Or explicitly specify stdio conceptnet-mcp-stdio # Or use Python module python -m conceptnet_mcp.server ``` #### HTTP Transport (for web clients) ```bash # Start HTTP server on localhost:3001 conceptnet-mcp-http # Or with custom host/port python -c "from conceptnet_mcp.server import run_http_server; run_http_server('0.0.0.0', 8080)" ``` #### Development Modes ```bash # Development mode with debug logging conceptnet-mcp-dev # Production mode with optimized logging conceptnet-mcp-prod ``` ### MCP Client Integration #### For Desktop MCP Clients (stdio transport) Add to your MCP client configuration: ```json { "mcpServers": { "conceptnet": { "command": "python", "args": ["-m", "conceptnet_mcp.server"] } } } ``` #### For Web Applications (HTTP transport) Add to your MCP client configuration: ```json { "mcpServers": { "conceptnet": { "command": "python", "args": ["-m", "conceptnet_mcp.server", "--transport", "http", "--port", "3001"] } } } ``` Or start the HTTP server manually and connect to: ``` http://localhost:3001 ``` ```javascript // Example web client connection const client = new MCPClient('http://localhost:3001'); await client.connect(); ``` ## โ˜๏ธ Cloudflare Workers Deployment Deploy ConceptNet MCP Server to Cloudflare's global edge network for worldwide access and automatic scaling using a **FastAPI-based implementation** optimized for Python Workers. [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/infinitnet/conceptnet-mcp) ### Architecture The Cloudflare Workers deployment uses a **completely different architecture** from the standard FastMCP server: - **FastAPI Framework**: Manual MCP protocol implementation using FastAPI for HTTP routing - **Standard Workers Pattern**: Uses `fetch(request, env, ctx)` handler (no Durable Objects) - **Native HTTP Client**: Custom `CloudflareHTTPClient` using Workers' native `fetch()` API - **Manual MCP Protocol**: JSON-RPC 2.0 MCP messages handled directly without FastMCP framework ### Benefits - ๐ŸŒ **Global Edge Network**: Low-latency access worldwide via Cloudflare's CDN - ๐Ÿš€ **Auto-scaling**: Serverless scaling based on demand with zero cold starts - ๐Ÿ”„ **Dual Transport Support**: Both SSE and Streamable HTTP endpoints for maximum compatibility - ๐Ÿค– **Remote MCP Access**: Enable AI agents to access ConceptNet from anywhere - ๐Ÿ’ฐ **Cost-effective**: Pay only for actual usage with generous free tier ### Quick Deploy ```bash # Clone and navigate to Workers directory git clone https://github.com/infinitnet/conceptnet-mcp.git cd conceptnet-mcp/cloudflare-workers # Install Wrangler CLI npm install -g wrangler # Authenticate and deploy wrangler login wrangler deploy ``` ### Usage After Deployment Your ConceptNet MCP Server will be available at: ``` # Streamable HTTP Transport (recommended for MCP clients) https://your-worker.your-domain.workers.dev/mcp # SSE Transport (legacy support) https://your-worker.your-domain.workers.dev/sse # Tools listing endpoint https://your-worker.your-domain.workers.dev/tools ``` **Example remote client connection (direct HTTP):** ```python import httpx import json # Connect to your deployed Workers instance async with httpx.AsyncClient() as client: response = await client.post( "https://your-worker.your-domain.workers.dev/mcp", json={ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "concept_lookup", "arguments": {"term": "artificial intelligence"} } } ) result = response.json() print(result["result"]) ``` For detailed deployment instructions, configuration options, and troubleshooting, see the [Cloudflare Workers Documentation](cloudflare-workers/README.md). ## Available Tools ### 1. Concept Lookup Get detailed information about a specific concept. Returns all relationships and properties. ```json { "name": "concept_lookup", "arguments": { "term": "artificial intelligence", "language": "en", "limit_results": false, "target_language": null, "verbose": false } } ``` **Parameters:** - `term` (required): The concept to look up - `language` (default: "en"): Language code for the concept - `limit_results` (default: false): Limit to first 20 results for quick queries - `target_language` (optional): Filter results to specific target language - `verbose` (default: false): Return detailed format vs minimal format ### 2. Concept Query Advanced querying with sophisticated multi-parameter filtering. ```json { "name": "concept_query", "arguments": { "start": "car", "rel": "IsA", "language": "en", "limit_results": false, "verbose": false } } ``` **Parameters:** - `start` (optional): Start concept of relationships - `end` (optional): End concept of relationships - `rel` (optional): Relation type (e.g., "IsA", "PartOf") - `node` (optional): Concept that must be start or end of edges - `other` (optional): Used with 'node' parameter - `sources` (optional): Filter by data source - `language` (default: "en"): Language filter - `limit_results` (default: false): Limit to 20 results for quick queries - `verbose` (default: false): Return detailed format vs minimal format ### 3. Related Concepts Find concepts semantically similar to a given concept using ConceptNet's embeddings. ```json { "name": "related_concepts", "arguments": { "term": "machine learning", "language": "en", "filter_language": null, "limit": 100, "verbose": false } } ``` **Parameters:** - `term` (required): The concept to find related concepts for - `language` (default: "en"): Language code for input term - `filter_language` (optional): Filter results to this language only - `limit` (default: 100, max: 100): Maximum number of related concepts - `verbose` (default: false): Return detailed format vs minimal format ### 4. Concept Relatedness Calculate precise semantic relatedness score between two concepts. ```json { "name": "concept_relatedness", "arguments": { "concept1": "artificial intelligence", "concept2": "machine learning", "language1": "en", "language2": "en", "verbose": false } } ``` **Parameters:** - `concept1` (required): First concept for comparison - `concept2` (required): Second concept for comparison - `language1` (default: "en"): Language for first concept - `language2` (default: "en"): Language for second concept - `verbose` (default: false): Return detailed format vs minimal format ## Configuration The server can be configured through environment variables: ```bash # ConceptNet API settings CONCEPTNET_API_BASE_URL=https://api.conceptnet.io CONCEPTNET_API_VERSION=5.7 # Server settings MCP_SERVER_HOST=localhost MCP_SERVER_PORT=3000 LOG_LEVEL=INFO # Rate limiting CONCEPTNET_RATE_LIMIT=100 CONCEPTNET_RATE_PERIOD=60 ``` ## Development ### Setup ```bash # Clone the repository git clone https://github.com/infinitnet/conceptnet-mcp.git cd conceptnet-mcp # Install in development mode pip install -e .[dev] # Install pre-commit hooks pre-commit install ``` ## API Reference ### Core Models - **Concept**: Represents a ConceptNet concept with URI, label, and language - **Edge**: Represents relationships between concepts with relation types - **Query**: Structured query parameters for concept searches - **Response**: Standardized response format with pagination support ### Client Components - **ConceptNetClient**: Async HTTP client for ConceptNet API - **PaginationHandler**: Automatic pagination for large result sets - **ResponseProcessor**: Data processing and normalization ### Utilities - **Text Processing**: Normalize text (underscores to spaces) - **Logging**: Structured logging with configurable levels - **Error Handling**: Comprehensive exception hierarchy ## Architecture ``` conceptnet_mcp/ โ”œโ”€โ”€ client/ # ConceptNet API client โ”‚ โ”œโ”€โ”€ conceptnet_client.py โ”‚ โ”œโ”€โ”€ pagination.py โ”‚ โ””โ”€โ”€ processor.py โ”œโ”€โ”€ models/ # Pydantic data models โ”‚ โ”œโ”€โ”€ concept.py โ”‚ โ”œโ”€โ”€ edge.py โ”‚ โ”œโ”€โ”€ query.py โ”‚ โ””โ”€โ”€ response.py โ”œโ”€โ”€ tools/ # MCP tool implementations โ”‚ โ”œโ”€โ”€ concept_lookup.py โ”‚ โ”œโ”€โ”€ concept_query.py โ”‚ โ”œโ”€โ”€ related_concepts.py โ”‚ โ””โ”€โ”€ concept_relatedness.py โ”œโ”€โ”€ utils/ # Utility modules โ”‚ โ”œโ”€โ”€ exceptions.py โ”‚ โ”œโ”€โ”€ logging.py โ”‚ โ””โ”€โ”€ text_utils.py โ””โ”€โ”€ server.py # FastMCP server entry point ``` ## Contributing 1. Fork the repository: https://github.com/infinitnet/conceptnet-mcp 2. Create a feature branch: `git checkout -b feature-name` 3. Make your changes and add tests 4. Run the test suite: `python run_tests.py` 5. Submit a pull request ### Guidelines - Follow PEP 8 style guidelines - Add type hints for all functions - Include docstrings for public APIs - Write tests for new functionality - Update documentation as needed ## License This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details. ## Acknowledgments - [ConceptNet](http://conceptnet.io/) for providing the semantic knowledge base - [FastMCP](https://github.com/jlowin/fastmcp) for the MCP framework - [Model Context Protocol](https://modelcontextprotocol.io/) specification ## Support - ๐Ÿ“– **Documentation**: [Read the docs](docs/) - ๐Ÿ› **Bug Reports**: [GitHub Issues](https://github.com/infinitnet/conceptnet-mcp/issues) - ๐Ÿ’ฌ **Discussions**: [GitHub Discussions](https://github.com/infinitnet/conceptnet-mcp/discussions) - ๐ŸŒ **Author's Website**: [https://infinitnet.io/](https://infinitnet.io/) --- Built with โค๏ธ for the AI and semantic web community.

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/infinitnet/conceptnet-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server