{"id":30580509,"url":"https://github.com/infinitnet/conceptnet-mcp","last_synced_at":"2025-10-15T22:14:58.642Z","repository":{"id":310838070,"uuid":"1041254983","full_name":"infinitnet/conceptnet-mcp","owner":"infinitnet","description":"ConceptNet MCP Server (Semantic Knowledge Graph for LLMs)","archived":false,"fork":false,"pushed_at":"2025-08-20T15:29:59.000Z","size":209,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-20T15:31:18.894Z","etag":null,"topics":["concept-extraction","conceptnet","knowledge-graph","semantic-search","semantic-seo","semantic-web"],"latest_commit_sha":null,"homepage":"https://infinitnet.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/infinitnet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-20T08:04:44.000Z","updated_at":"2025-08-20T15:30:03.000Z","dependencies_parsed_at":"2025-08-20T15:31:28.539Z","dependency_job_id":"5ce12bd7-bcbe-43fe-aa75-21608e8d7fb4","html_url":"https://github.com/infinitnet/conceptnet-mcp","commit_stats":null,"previous_names":["infinitnet/conceptnet-mcp"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/infinitnet/conceptnet-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinitnet%2Fconceptnet-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinitnet%2Fconceptnet-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinitnet%2Fconceptnet-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinitnet%2Fconceptnet-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infinitnet","download_url":"https://codeload.github.com/infinitnet/conceptnet-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinitnet%2Fconceptnet-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272636079,"owners_count":24967982,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["concept-extraction","conceptnet","knowledge-graph","semantic-search","semantic-seo","semantic-web"],"created_at":"2025-08-29T05:35:52.726Z","updated_at":"2025-10-15T22:14:58.557Z","avatar_url":"https://github.com/infinitnet.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ConceptNet MCP Server\n\nA Model Context Protocol (MCP) server that provides seamless access to the ConceptNet knowledge graph through FastMCP framework.\n\n[![CI](https://github.com/infinitnet/conceptnet-mcp/workflows/CI/badge.svg)](https://github.com/infinitnet/conceptnet-mcp/actions/workflows/ci.yml)\n[![Release](https://github.com/infinitnet/conceptnet-mcp/workflows/Release/badge.svg)](https://github.com/infinitnet/conceptnet-mcp/actions/workflows/release.yml)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\n## Overview\n\nConceptNet MCP provides AI assistants and applications with structured access to ConceptNet's semantic knowledge through four powerful MCP tools:\n\n- **Concept Lookup**: Get detailed information about specific concepts\n- **Concept Query**: Search and filter concepts with advanced criteria  \n- **Related Concepts**: Find concepts connected through semantic relationships\n- **Concept Relatedness**: Calculate semantic similarity between concepts\n\n## Features\n\n- 🚀 **FastMCP Integration**: Built on the modern FastMCP framework for optimal performance\n- 🔍 **Comprehensive Search**: Advanced querying with language filtering and pagination\n- 🌐 **Multi-language Support**: Access ConceptNet's multilingual knowledge base\n- 📊 **Semantic Analysis**: Calculate relatedness scores between concepts\n- 🔄 **Async Operations**: Full async/await support for non-blocking operations\n- 📝 **Type Safety**: Complete Pydantic v2 type validation and IDE support\n- 🧪 **Production Ready**: Error handling, logging, and testing\n- ⚡ **Optimized Output Formats**: Choose between minimal (~96% smaller) or comprehensive responses\n\n## Output Formats\n\nConceptNet MCP Server supports two output formats for all tools to optimize performance and reduce token usage:\n\n### Minimal Format (Default - Recommended)\n- **Size**: ~96% smaller than verbose format\n- **Optimized**: Designed specifically for LLM consumption\n- **Content**: Essential data only - concepts, relationships, similarity scores\n- **Performance**: Faster processing and reduced API costs\n- **Usage**: Perfect for most AI applications and chat interfaces\n\n### Verbose Format\n- **Size**: Full ConceptNet response data\n- **Content**: Complete metadata, statistics, analysis, and original API responses\n- **Usage**: Detailed analysis, debugging, or when full context is needed\n- **Backward Compatibility**: Maintains compatibility with existing integrations\n\n### Setting the Format\n\nAll tools accept a `verbose` parameter:\n\n```json\n{\n  \"name\": \"concept_lookup\",\n  \"arguments\": {\n    \"term\": \"artificial intelligence\",\n    \"verbose\": false  // Default: minimal format\n  }\n}\n```\n\n```json\n{\n  \"name\": \"related_concepts\",\n  \"arguments\": {\n    \"term\": \"machine learning\",\n    \"verbose\": true   // Full detailed format\n  }\n}\n```\n\n**Examples of size difference:**\n- Minimal: `{\"concept\": \"dog\", \"relationships\": {\"IsA\": [\"animal\", \"mammal\"]}}`\n- Verbose: Full ConceptNet response with complete metadata, statistics, timestamps, etc.\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/infinitnet/conceptnet-mcp.git\ncd conceptnet-mcp\n\n# Install in development mode\npip install -e .\n```\n\n### Running the MCP Server\n\nThe server supports both **stdio** (for desktop MCP clients) and **HTTP** (for web clients) transport modes:\n\n#### Stdio Transport (Default - for desktop MCP clients)\n```bash\n# Start with stdio transport (default)\nconceptnet-mcp\n\n# Or explicitly specify stdio\nconceptnet-mcp-stdio\n\n# Or use Python module\npython -m conceptnet_mcp.server\n```\n\n#### HTTP Transport (for web clients)\n```bash\n# Start HTTP server on localhost:3001\nconceptnet-mcp-http\n\n# Or with custom host/port\npython -c \"from conceptnet_mcp.server import run_http_server; run_http_server('0.0.0.0', 8080)\"\n```\n\n#### Development Modes\n```bash\n# Development mode with debug logging\nconceptnet-mcp-dev\n\n# Production mode with optimized logging\nconceptnet-mcp-prod\n```\n\n### MCP Client Integration\n\n#### For Desktop MCP Clients (stdio transport)\nAdd to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"conceptnet\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"conceptnet_mcp.server\"]\n    }\n  }\n}\n```\n\n#### For Web Applications (HTTP transport)\nAdd to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"conceptnet\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"conceptnet_mcp.server\", \"--transport\", \"http\", \"--port\", \"3001\"]\n    }\n  }\n}\n```\n\nOr start the HTTP server manually and connect to:\n```\nhttp://localhost:3001\n```\n\n```javascript\n// Example web client connection\nconst client = new MCPClient('http://localhost:3001');\nawait client.connect();\n```\n\n## ☁️ Cloudflare Workers Deployment\n\nDeploy ConceptNet MCP Server to Cloudflare's global edge network for worldwide access and automatic scaling using a **FastAPI-based implementation** optimized for Python Workers.\n\n[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/infinitnet/conceptnet-mcp)\n\n### Architecture\n\nThe Cloudflare Workers deployment uses a **completely different architecture** from the standard FastMCP server:\n\n- **FastAPI Framework**: Manual MCP protocol implementation using FastAPI for HTTP routing\n- **Standard Workers Pattern**: Uses `fetch(request, env, ctx)` handler (no Durable Objects)\n- **Native HTTP Client**: Custom `CloudflareHTTPClient` using Workers' native `fetch()` API\n- **Manual MCP Protocol**: JSON-RPC 2.0 MCP messages handled directly without FastMCP framework\n\n### Benefits\n\n- 🌍 **Global Edge Network**: Low-latency access worldwide via Cloudflare's CDN\n- 🚀 **Auto-scaling**: Serverless scaling based on demand with zero cold starts\n- 🔄 **Dual Transport Support**: Both SSE and Streamable HTTP endpoints for maximum compatibility\n- 🤖 **Remote MCP Access**: Enable AI agents to access ConceptNet from anywhere\n- 💰 **Cost-effective**: Pay only for actual usage with generous free tier\n\n### Quick Deploy\n\n```bash\n# Clone and navigate to Workers directory\ngit clone https://github.com/infinitnet/conceptnet-mcp.git\ncd conceptnet-mcp/cloudflare-workers\n\n# Install Wrangler CLI\nnpm install -g wrangler\n\n# Authenticate and deploy\nwrangler login\nwrangler deploy\n```\n\n### Usage After Deployment\n\nYour ConceptNet MCP Server will be available at:\n\n```\n# Streamable HTTP Transport (recommended for MCP clients)\nhttps://your-worker.your-domain.workers.dev/mcp\n\n# SSE Transport (legacy support)\nhttps://your-worker.your-domain.workers.dev/sse\n\n# Tools listing endpoint\nhttps://your-worker.your-domain.workers.dev/tools\n```\n\n**Example remote client connection (direct HTTP):**\n```python\nimport httpx\nimport json\n\n# Connect to your deployed Workers instance\nasync with httpx.AsyncClient() as client:\n    response = await client.post(\n        \"https://your-worker.your-domain.workers.dev/mcp\",\n        json={\n            \"jsonrpc\": \"2.0\",\n            \"id\": 1,\n            \"method\": \"tools/call\",\n            \"params\": {\n                \"name\": \"concept_lookup\",\n                \"arguments\": {\"term\": \"artificial intelligence\"}\n            }\n        }\n    )\n    result = response.json()\n    print(result[\"result\"])\n```\n\nFor detailed deployment instructions, configuration options, and troubleshooting, see the [Cloudflare Workers Documentation](cloudflare-workers/README.md).\n\n## Available Tools\n\n### 1. Concept Lookup\n\nGet detailed information about a specific concept. Returns all relationships and properties.\n\n```json\n{\n  \"name\": \"concept_lookup\",\n  \"arguments\": {\n    \"term\": \"artificial intelligence\",\n    \"language\": \"en\",\n    \"limit_results\": false,\n    \"target_language\": null,\n    \"verbose\": false\n  }\n}\n```\n\n**Parameters:**\n- `term` (required): The concept to look up\n- `language` (default: \"en\"): Language code for the concept\n- `limit_results` (default: false): Limit to first 20 results for quick queries\n- `target_language` (optional): Filter results to specific target language\n- `verbose` (default: false): Return detailed format vs minimal format\n\n### 2. Concept Query\n\nAdvanced querying with sophisticated multi-parameter filtering.\n\n```json\n{\n  \"name\": \"concept_query\",\n  \"arguments\": {\n    \"start\": \"car\",\n    \"rel\": \"IsA\",\n    \"language\": \"en\",\n    \"limit_results\": false,\n    \"verbose\": false\n  }\n}\n```\n\n**Parameters:**\n- `start` (optional): Start concept of relationships\n- `end` (optional): End concept of relationships\n- `rel` (optional): Relation type (e.g., \"IsA\", \"PartOf\")\n- `node` (optional): Concept that must be start or end of edges\n- `other` (optional): Used with 'node' parameter\n- `sources` (optional): Filter by data source\n- `language` (default: \"en\"): Language filter\n- `limit_results` (default: false): Limit to 20 results for quick queries\n- `verbose` (default: false): Return detailed format vs minimal format\n\n### 3. Related Concepts\n\nFind concepts semantically similar to a given concept using ConceptNet's embeddings.\n\n```json\n{\n  \"name\": \"related_concepts\",\n  \"arguments\": {\n    \"term\": \"machine learning\",\n    \"language\": \"en\",\n    \"filter_language\": null,\n    \"limit\": 100,\n    \"verbose\": false\n  }\n}\n```\n\n**Parameters:**\n- `term` (required): The concept to find related concepts for\n- `language` (default: \"en\"): Language code for input term\n- `filter_language` (optional): Filter results to this language only\n- `limit` (default: 100, max: 100): Maximum number of related concepts\n- `verbose` (default: false): Return detailed format vs minimal format\n\n### 4. Concept Relatedness\n\nCalculate precise semantic relatedness score between two concepts.\n\n```json\n{\n  \"name\": \"concept_relatedness\",\n  \"arguments\": {\n    \"concept1\": \"artificial intelligence\",\n    \"concept2\": \"machine learning\",\n    \"language1\": \"en\",\n    \"language2\": \"en\",\n    \"verbose\": false\n  }\n}\n```\n\n**Parameters:**\n- `concept1` (required): First concept for comparison\n- `concept2` (required): Second concept for comparison\n- `language1` (default: \"en\"): Language for first concept\n- `language2` (default: \"en\"): Language for second concept\n- `verbose` (default: false): Return detailed format vs minimal format\n\n## Configuration\n\nThe server can be configured through environment variables:\n\n```bash\n# ConceptNet API settings\nCONCEPTNET_API_BASE_URL=https://api.conceptnet.io\nCONCEPTNET_API_VERSION=5.7\n\n# Server settings\nMCP_SERVER_HOST=localhost\nMCP_SERVER_PORT=3000\nLOG_LEVEL=INFO\n\n# Rate limiting\nCONCEPTNET_RATE_LIMIT=100\nCONCEPTNET_RATE_PERIOD=60\n```\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/infinitnet/conceptnet-mcp.git\ncd conceptnet-mcp\n\n# Install in development mode\npip install -e .[dev]\n\n# Install pre-commit hooks\npre-commit install\n```\n\n## API Reference\n\n### Core Models\n\n- **Concept**: Represents a ConceptNet concept with URI, label, and language\n- **Edge**: Represents relationships between concepts with relation types\n- **Query**: Structured query parameters for concept searches\n- **Response**: Standardized response format with pagination support\n\n### Client Components\n\n- **ConceptNetClient**: Async HTTP client for ConceptNet API\n- **PaginationHandler**: Automatic pagination for large result sets\n- **ResponseProcessor**: Data processing and normalization\n\n### Utilities\n\n- **Text Processing**: Normalize text (underscores to spaces)\n- **Logging**: Structured logging with configurable levels\n- **Error Handling**: Comprehensive exception hierarchy\n\n## Architecture\n\n```\nconceptnet_mcp/\n├── client/           # ConceptNet API client\n│   ├── conceptnet_client.py\n│   ├── pagination.py\n│   └── processor.py\n├── models/           # Pydantic data models\n│   ├── concept.py\n│   ├── edge.py\n│   ├── query.py\n│   └── response.py\n├── tools/            # MCP tool implementations\n│   ├── concept_lookup.py\n│   ├── concept_query.py\n│   ├── related_concepts.py\n│   └── concept_relatedness.py\n├── utils/            # Utility modules\n│   ├── exceptions.py\n│   ├── logging.py\n│   └── text_utils.py\n└── server.py         # FastMCP server entry point\n```\n\n## Contributing\n\n1. Fork the repository: https://github.com/infinitnet/conceptnet-mcp\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes and add tests\n4. Run the test suite: `python run_tests.py`\n5. Submit a pull request\n\n### Guidelines\n\n- Follow PEP 8 style guidelines\n- Add type hints for all functions\n- Include docstrings for public APIs\n- Write tests for new functionality\n- Update documentation as needed\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [ConceptNet](http://conceptnet.io/) for providing the semantic knowledge base\n- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP framework\n- [Model Context Protocol](https://modelcontextprotocol.io/) specification\n\n## Support\n\n- 📖 **Documentation**: [Read the docs](docs/)\n- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/infinitnet/conceptnet-mcp/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/infinitnet/conceptnet-mcp/discussions)\n- 🌐 **Author's Website**: [https://infinitnet.io/](https://infinitnet.io/)\n\n---\n\nBuilt with ❤️ for the AI and semantic web community.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfinitnet%2Fconceptnet-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfinitnet%2Fconceptnet-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfinitnet%2Fconceptnet-mcp/lists"}