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.
[](https://github.com/infinitnet/conceptnet-mcp/actions/workflows/ci.yml)
[](https://github.com/infinitnet/conceptnet-mcp/actions/workflows/release.yml)
[](https://www.python.org/downloads/)
[](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.
[](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.