Yet Sparql Mcp Server

MCP SPARQL Server

🌟 概要

MCP SPARQL Serverは、あらゆるSPARQLエンドポイントに接続し、結果のフォーマットやキャッシュなどの拡張機能を提供する、高性能で設定可能なサーバーです。Model Context Protocol（MCP）を実装するFastMCPフレームワーク上に構築されており、AIアシスタントがセマンティックデータをシームレスにクエリできるインターフェースを提供します。

✨ 機能

• あらゆるエンドポイントに対応：SPARQL準拠のあらゆるエンドポイントに接続できます
• SPARQLを完全サポート：有効なSPARQLクエリ（SELECT、ASK、CONSTRUCT、DESCRIBE）を実行できます
• インテリジェントな結果フォーマット：
  • 標準JSON（標準的なSPARQLクライアントと互換）
  • シンプルなJSON（アプリケーションで扱いやすい形式）
  • 表形式（UIのテーブルにそのまま表示可能）
• 高性能なキャッシュ：
  • 複数のキャッシュ戦略（LRU、LFU、FIFO）
  • 設定可能なTTL（有効期間）
  • キャッシュ管理ツール
• 柔軟なデプロイオプション：
  • stdioまたはHTTPトランスポートを使ってフォアグラウンドモードで実行
  • バックグラウンドデーモンとして実行
  • systemdサービスとしてデプロイ
  • nginxリバースプロキシとの連携に対応したHTTPサーバーモード
• 包括的な設定：
  • コマンドライン引数
  • 環境変数
  • ハードコードされた値なし

📋 要件

• Python 3.8以降
• SPARQLWrapperライブラリ
• fastmcpフレームワーク
• 設定用のpydantic
• バックグラウンド実行用のpython-daemon

🚀 インストール

ソースから

# Clone the repository
git clone https://github.com/yet-market/yet-sparql-mcp-server.git
cd yet-sparql-mcp-server

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

PyPIから

pip install mcp-server-sparql

インストールスクリプトを使用

systemdサービスの設定を含む完全なインストールを行う場合：

# Download the repository
git clone https://github.com/yet-market/yet-sparql-mcp-server.git
cd yet-sparql-mcp-server

# Run the installation script (as root for systemd service)
sudo ./install.sh

インストーラーは以下を自動的に実行します：

• 仮想環境と依存関係を設定
• systemdサービスを作成して起動
• 簡単に操作できる管理スクリプトを提供
• nginxとの連携用にHTTPサービスを設定

簡単な管理

インストール後、付属のスクリプトを使用します：

# Check status
./status.sh

# Start/stop services
./start.sh [stdio|http]    # Start service (http is default)
./stop.sh [stdio|http]     # Stop service
./logs.sh [stdio|http]     # View logs

# Examples
./start.sh http            # Start HTTP service for nginx
./logs.sh http             # View HTTP service logs
./test.sh                  # Test server functionality
./stop.sh                  # Stop all services

インストールのテスト

組み込みのテストスイートでサーバーをテストします：

# Run comprehensive tests
./test.sh

# Run specific tests
./test.sh endpoint         # Test HTTP connectivity
./test.sh service          # Test service status
./test.sh config           # Test configuration
./test.sh mcp              # Test MCP protocol
./test.sh client           # Test with FastMCP client
./test.sh info             # Show connection info

テストスクリプトは以下を検証します：

• ✅ サービスの状態と正常性
• ✅ HTTPエンドポイントへの接続性
• ✅ MCPプロトコルへの準拠
• ✅ 設定の妥当性
• ✅ SPARQLエンドポイントへの到達性
• ✅ FastMCPクライアントとの連携

🔍 使い方

基本的な使い方（stdioトランスポート）

SPARQLエンドポイントを指定してサーバーを起動します：

python server.py --endpoint https://dbpedia.org/sparql

HTTPサーバーモード（nginx／Web連携用）

サーバーをHTTPサーバーとして実行します：

# Basic HTTP server
python server.py --transport http --endpoint https://dbpedia.org/sparql

# Custom host and port
python server.py --transport http --host 0.0.0.0 --port 8080 --endpoint https://dbpedia.org/sparql

# Using environment variables
export MCP_TRANSPORT=http
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
export SPARQL_ENDPOINT=https://dbpedia.org/sparql
python server.py

デーモンとして実行

サーバーをバックグラウンドプロセスとして実行する場合（stdioトランスポート）：

python server.py --endpoint https://dbpedia.org/sparql --daemon \
  --log-file /var/log/mcp-sparql.log \
  --pid-file /var/run/mcp-sparql.pid

HTTPサーバーをデーモンとして実行する場合：

python server.py --transport http --host 0.0.0.0 --port 8000 \
  --endpoint https://dbpedia.org/sparql --daemon \
  --log-file /var/log/mcp-sparql.log \
  --pid-file /var/run/mcp-sparql.pid

Systemdでの使用

systemdサポートを有効にしてインストールした場合：

1. 環境ファイルでエンドポイントを設定します：

   sudo nano /etc/mcp-sparql/env
   

2. サービスを起動します：

   sudo systemctl start sparql-server
   

3. 起動時に自動起動するよう設定します：

   sudo systemctl enable sparql-server
   

クライアントのクエリ例

サーバーの起動後は、MCP互換の任意のクライアント、またはFastMCPクライアントを使って利用できます：

stdioトランスポートでFastMCPクライアントを使用（Python）

import asyncio
from fastmcp.client import Client, PythonStdioTransport

async def query_server():
    # Connect to the server
    transport = PythonStdioTransport(
        script_path="server.py",
        args=["--endpoint", "https://dbpedia.org/sparql"]
    )
    
    async with Client(transport) as client:
        # Execute a SPARQL query
        result = await client.call_tool("query", {
            "query_string": "SELECT * WHERE { ?s ?p ?o } LIMIT 5",
            "format": "simplified"
        })
        
        print(result[0].text)

asyncio.run(query_server())

HTTPトランスポートでFastMCPクライアントを使用（Python）

import asyncio
from fastmcp.client import Client, HttpTransport

async def query_server():
    # Connect to HTTP server
    transport = HttpTransport("http://localhost:8000")
    
    async with Client(transport) as client:
        # Execute a SPARQL query
        result = await client.call_tool("query", {
            "query_string": "SELECT * WHERE { ?s ?p ?o } LIMIT 5",
            "format": "simplified"
        })
        
        print(result[0].text)

asyncio.run(query_server())

さまざまな形式でクエリ

# JSON format (default)
result = await client.call_tool("query", {
    "query_string": "SELECT * WHERE { ?s ?p ?o } LIMIT 5",
    "format": "json"
})

# Tabular format
result = await client.call_tool("query", {
    "query_string": "SELECT * WHERE { ?s ?p ?o } LIMIT 5",
    "format": "tabular"
})

キャッシュ管理

# Get cache statistics
cache_stats = await client.call_tool("cache", {"action": "stats"})

# Clear the cache
cache_clear = await client.call_tool("cache", {"action": "clear"})

⚙️ 設定

コマンドライン引数

引数	説明	デフォルト
--endpoint URL	SPARQL エンドポイントの URL	必須
--timeout SECONDS	リクエストのタイムアウト（秒）	30
--format FORMAT	結果の形式（json、simplified、tabular）	json
--cache-enabled BOOL	結果のキャッシュを有効にする	true
--cache-ttl SECONDS	キャッシュの有効期間（秒）	300
--cache-max-size SIZE	キャッシュの最大サイズ	100
--cache-strategy STRATEGY	キャッシュの置換戦略（lru、lfu、fifo）	lru
--pretty-print	JSON 出力を整形する	false
--include-metadata BOOL	結果にクエリのメタデータを含める	true
--daemon	バックグラウンドデーモンとして実行する	false
--log-file FILE	デーモン実行時のログファイルの場所	/var/log/mcp-sparql-server.log
--pid-file FILE	デーモン実行時の PID ファイルの場所	/var/run/mcp-sparql-server.pid
--transport TRANSPORT	トランスポートの種類（stdio または http）	stdio
--host HOST	HTTP サーバーをバインドするホスト	localhost
--port PORT	HTTP サーバーをバインドするポート	8000

環境変数

変数	説明	デフォルト
SPARQL_ENDPOINT	SPARQL エンドポイントの URL	なし（必須）
SPARQL_TIMEOUT	リクエストのタイムアウト（秒）	30
SPARQL_FORMAT	デフォルトの結果形式	json
SPARQL_CACHE_ENABLED	キャッシュを有効にする	true
SPARQL_CACHE_TTL	キャッシュの有効期間（秒）	300
SPARQL_CACHE_MAX_SIZE	キャッシュの最大サイズ	100
SPARQL_CACHE_STRATEGY	キャッシュの置換戦略	lru
SPARQL_PRETTY_PRINT	JSON 出力を整形する	false
SPARQL_INCLUDE_METADATA	結果にクエリのメタデータを含める	true
MCP_TRANSPORT	トランスポートの種類（stdio または http）	stdio
MCP_HOST	HTTP サーバーをバインドするホスト	localhost
MCP_PORT	HTTP サーバーをバインドするポート	8000

🌐 Nginx との連携

HTTP トランスポートを使用する場合、サーバーをリバースプロキシとして nginx と連携できます。

1. HTTP モードでサーバーを起動する

python server.py --transport http --host localhost --port 8000 --endpoint https://your-sparql-endpoint.com/sparql

2. nginx を設定する

この設定を nginx のサーバーブロックに追加します。

upstream mcp_sparql {
    server localhost:8000;
    # Add more servers for load balancing if needed
    # server localhost:8001;
    # server localhost:8002;
}

server {
    listen 80;
    server_name your-domain.com;

    location /api/sparql {
        proxy_pass http://mcp_sparql;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Optional: Add CORS headers
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
        add_header Access-Control-Allow-Headers "Content-Type, Authorization";
    }
}

3. systemd を使用した本番環境へのデプロイ

HTTP モード用の systemd サービスを作成します。

# /etc/systemd/system/mcp-sparql-http.service
[Unit]
Description=MCP SPARQL Server (HTTP)
After=network.target

[Service]
Type=simple
User=mcp-sparql
Group=mcp-sparql
WorkingDirectory=/opt/mcp-sparql
Environment=MCP_TRANSPORT=http
Environment=MCP_HOST=localhost
Environment=MCP_PORT=8000
Environment=SPARQL_ENDPOINT=https://your-sparql-endpoint.com/sparql
ExecStart=/opt/mcp-sparql/venv/bin/python server.py
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

サービスを有効にして起動します。

sudo systemctl enable mcp-sparql-http
sudo systemctl start mcp-sparql-http

📊 結果の形式

サーバーは、3 種類の出力形式に対応しています。

1. JSON 形式（デフォルト）

オプションのメタデータを含む、標準の SPARQL JSON 結果形式を返します。

{
  "head": {
    "vars": ["s", "p", "o"]
  },
  "results": {
    "bindings": [
      {
        "s": { "type": "uri", "value": "http://example.org/resource" },
        "p": { "type": "uri", "value": "http://example.org/property" },
        "o": { "type": "literal", "value": "Example Value" }
      }
    ]
  },
  "metadata": {
    "variables": ["s", "p", "o"],
    "count": 1,
    "query": "SELECT * WHERE { ?s ?p ?o } LIMIT 1"
  }
}

2. 簡易形式

変数のバインディングをシンプルなキーと値のオブジェクトに変換した、扱いやすい簡易 JSON 構造を返します。

{
  "type": "SELECT",
  "results": [
    {
      "s": "http://example.org/resource",
      "p": "http://example.org/property",
      "o": "Example Value"
    }
  ],
  "metadata": {
    "variables": ["s", "p", "o"],
    "count": 1,
    "query": "SELECT * WHERE { ?s ?p ?o } LIMIT 1"
  }
}

3. 表形式

テーブル表示に適した、列と行で構成される表形式で結果を返します。

{
  "type": "SELECT",
  "columns": [
    { "name": "s", "label": "s" },
    { "name": "p", "label": "p" },
    { "name": "o", "label": "o" }
  ],
  "rows": [
    [
      "http://example.org/resource",
      "http://example.org/property",
      "Example Value"
    ]
  ],
  "metadata": {
    "variables": ["s", "p", "o"],
    "count": 1,
    "query": "SELECT * WHERE { ?s ?p ?o } LIMIT 1"
  }
}

🔄 キャッシュ戦略

サーバーは、3 種類のキャッシュ置換戦略に対応しています。

1. LRU（Least Recently Used）

最後にアクセスされた時刻が最も古い項目から削除します。デフォルトの戦略であり、最近アクセスされた項目をキャッシュに保持するため、ほとんどのシナリオで適切に機能します。

2. LFU（Least Frequently Used）

アクセス頻度が最も低い項目から削除します。この戦略は、他よりも頻繁に実行されるクエリがあるシナリオに適しており、アクセス頻度の高い項目をキャッシュに保持します。

3. FIFO（First In First Out）

アクセス状況に関係なく、最も古い項目から削除します。この戦略はシンプルで、純粋に時間に基づくキャッシュ方式を使いたい場合に便利です。

🔍 高度な SPARQL の例

サーバーは、すべての SPARQL 機能に対応しています。試してみることができるクエリの例を以下に示します。

基本的なトリプルパターン

SELECT * WHERE { ?s ?p ?o } LIMIT 10

プロパティの型によるフィルタリング

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?subject ?label
WHERE {
    ?subject rdf:type rdfs:Class ;
             rdfs:label ?label .
}
LIMIT 10

正規表現の使用

PREFIX foaf: <http://xmlns.com/foaf/0.1/>

SELECT ?person ?name
WHERE {
    ?person foaf:name ?name .
    FILTER(REGEX(?name, "Smith", "i"))
}
LIMIT 10

複数のパターンを使った複雑なクエリ

PREFIX dbo: <http://dbpedia.org/ontology/>
PREFIX dbp: <http://dbpedia.org/property/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?city ?name ?population ?country ?countryName
WHERE {
    ?city a dbo:City ;
          rdfs:label ?name ;
          dbo:population ?population ;
          dbo:country ?country .
    ?country rdfs:label ?countryName .
    FILTER(?population > 1000000)
    FILTER(LANG(?name) = 'en')
    FILTER(LANG(?countryName) = 'en')
}
ORDER BY DESC(?population)
LIMIT 10

⚠️ トラブルシューティング

よくある問題

• 接続が拒否される：SPARQL エンドポイントの URL が正しく、アクセス可能であることを確認してください
• クエリがタイムアウトする：--timeout オプションでタイムアウト値を増やしてください
• 大きな結果セットによるメモリの問題：クエリに LIMIT 句を追加するか、キャッシュサイズを小さくしてください
• ログ／PID ファイルへのアクセスが拒否される：ディレクトリの権限を確認するか、適切な権限で実行してください

ロギング

フォアグラウンドモードで実行すると、ログはコンソールに出力されます。デーモンとして実行すると、ログは指定したログファイル（デフォルト：/var/log/mcp-sparql-server.log）に書き込まれます。

詳細なログを出力するには、ソースコードで Python のログレベルを設定します。

🛠️ 開発

プロジェクト構成

mcp-server-sparql/
├── sparql_server/             # Main package
│   ├── core/                  # Core functionality
│   │   ├── __init__.py        # Package exports
│   │   ├── config.py          # Configuration management
│   │   └── server.py          # Main SPARQL server
│   ├── formatters/            # Result formatters
│   │   ├── __init__.py        # Package exports
│   │   ├── formatter.py       # Base formatter class
│   │   ├── json_formatter.py  # JSON formatter
│   │   ├── simplified_formatter.py # Simplified JSON formatter
│   │   └── tabular_formatter.py # Tabular formatter
│   ├── cache/                 # Caching implementation
│   │   ├── __init__.py        # Package exports
│   │   ├── query_cache.py     # Base cache interface
│   │   ├── lru_cache.py       # LRU cache implementation
│   │   ├── lfu_cache.py       # LFU cache implementation
│   │   └── fifo_cache.py      # FIFO cache implementation
│   └── __init__.py            # Package exports
├── server.py                  # Main entry point
├── setup.py                   # Package setup
├── install.sh                 # Installation script
├── requirements.txt           # Python dependencies
├── sparql-server.service      # Systemd service file
├── README.md                  # This file
└── LICENSE                    # License file

テストの実行

# Test stdio transport
python test_sparql_server.py

# Test HTTP transport (start server first)
# Terminal 1:
python server.py --transport http --endpoint https://dbpedia.org/sparql
# Terminal 2:
# Run HTTP-specific tests (if available)

🔒 セキュリティに関する考慮事項

• サーバーは認証や認可を実装しておらず、基盤となる SPARQL エンドポイントのセキュリティに依存します
• 本番環境で使用する場合は、安全なプロキシの背後にデプロイすることを検討してください
• 信頼できないクエリはリソースを大量に消費する可能性があるため、注意して扱ってください

📄 ライセンス

このプロジェクトは、デュアルライセンスモデルで提供されています。

• オープンソース：オープンソースでの使用には GNU Affero General Public License v3.0（AGPL-3.0）
• 商用：商用またはプロプライエタリな用途には、プロプライエタリな商用ライセンスを利用できます

詳細については、LICENSE ファイルを参照してください。

このソフトウェアは、Temkit Sid-Ali が Yet.lu 向けに構想・開発し、Claude（Anthropic）、GitHub Copilot/Codex（OpenAI）、GPT-o3（OpenAI）の AI 支援を受けています。

🚀 ロードマップ

今後に向けた魅力的な計画があります！次の予定を含む詳細なロードマップをご覧ください。

• 🔒 セキュリティと認証の強化
• 🌐 クエリ探索のためのウェブインターフェース
• 🤖 AI を活用した自然言語から SPARQL への変換
• 📊 高度なデータ可視化と分析
• 🏢 エンタープライズ機能とスケーラビリティの向上

🤝 貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

開発環境のセットアップとガイドラインの詳細については、貢献ガイドをご覧ください。

🙏 謝辞

このプロジェクトは、いくつかの優れたオープンソースプロジェクトを基盤として構築されています。

• FastMCP - Joel Lowin 氏による、MCP サーバーとクライアントを構築するための高レベルな Python フレームワーク
• SPARQLWrapper - RDFLib チームによる、Python 用 SPARQL エンドポイントインターフェース
• Pydantic - Samuel Colvin 氏および Pydantic チームによる、Python の型ヒントを使用したデータ検証
• python-daemon - Unix デーモンプロセスを作成するためのライブラリ

特に感謝いたします：

• プロトコル仕様の開発に取り組んでいる Model Context Protocol (MCP) コミュニティ
• AI アシスタントと MCP エコシステムに取り組んでいる Anthropic
• 基礎的な取り組みを続けている セマンティックウェブ と RDF のコミュニティ
• SPARQL の仕様と標準を策定している W3C
• AI 開発パートナー：
  • Claude (Anthropic) - アーキテクチャ、コード実装、ドキュメント作成を支援した主要な開発アシスタント
  • GitHub Copilot/Codex (OpenAI) - コード補完と開発の高速化
  • GPT-o3 (OpenAI) - 高度な推論と問題解決の支援

📬 お問い合わせ

• GitHub Issues：https://github.com/yet-market/yet-sparql-mcp-server/issues
• ウェブサイト：https://yet.lu
• 開発に関するお問い合わせ：[email protected]
• 商用ライセンスに関するお問い合わせ：[email protected]

---