Codemode Sqlite MCP

🚀 codemode-sqlite-mcp

このプロジェクトは、高性能なSQLite MCP（Model Context Protocol）サーバーです。Codemodeという実験的なコード生成アプローチを採用しており、LLM（Large Language Model）が逐次的なツール呼び出しではなく、生成されたGoコードを通じてデータベース操作を実行できるようにします。

🚀 クイックスタート

📦 インストール

以下のコマンドを使用してインストールします。

go install github.com/imran31415/codemode-sqlite-mcp@latest

または、ソースからビルドすることもできます。

git clone https://github.com/imran31415/codemode-sqlite-mcp.git
cd codemode-sqlite-mcp
go build -o codemode-sqlite-mcp .

💻 使用例

基本的な使用法

MCPサーバーとして（Claude Desktop用）

codemode-sqlite-mcp --mode=stdio --db=./mydata.db

HTTPサーバーとして

codemode-sqlite-mcp --mode=http --port=8084 --db=./mydata.db

対話型Codemodeエージェントとして

export ANTHROPIC_API_KEY="your-api-key"
codemode-sqlite-mcp --mode=codemode --db=./mydata.db

Claude Desktopの設定

Claude DesktopのMCP設定ファイルに以下を追加します。

{
  "mcpServers": {
    "codemode-sqlite": {
      "command": "codemode-sqlite-mcp",
      "args": ["--mode=stdio", "--db=/path/to/database.db"]
    }
  }
}

📚 ドキュメント

概要

このパッケージは、LLMとデータベースの相互作用に関する2つの異なるアプローチを提供します。

1. 標準MCPモード：SQLite操作をMCPツールとして公開し、LLMが逐次的に呼び出すことができます。
2. Codemode：LLMが完全なGoプログラムを生成し、一度にデータベース操作を実行します。

Codemodeアプローチは、複雑なデータベース操作において、トークン使用量とレイテンシの面で大幅な効率向上を示します。

アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                    codemode-sqlite-mcp                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────────┐   │
│  │   MCP       │   │  Codemode   │   │    SQLite       │   │
│  │   Server    │   │    Agent    │   │    Tools        │   │
│  │             │   │             │   │                 │   │
│  │  - stdio    │   │  - LLM API  │   │  - db_info      │   │
│  │  - http     │   │  - Code Gen │   │  - list_tables  │   │
│  │             │   │  - Executor │   │  - query        │   │
│  └──────┬──────┘   └──────┬──────┘   │  - CRUD ops     │   │
│         │                 │          └────────┬────────┘   │
│         └────────┬────────┘                   │            │
│                  │                            │            │
│           ┌──────▼────────────────────────────▼──────┐     │
│           │              Tool Registry               │     │
│           │    (Unified interface for all tools)     │     │
│           └──────────────────────────────────────────┘     │
│                              │                             │
│                    ┌─────────▼─────────┐                   │
│                    │   SQLite Database │                   │
│                    │  (modernc.org/    │                   │
│                    │   sqlite - pure   │                   │
│                    │   Go, no CGO)     │                   │
│                    └───────────────────┘                   │
└─────────────────────────────────────────────────────────────┘

利用可能なツール

このパッケージは、MCPを介して8つのSQLite操作を公開しています。

Codemode: コード生成アプローチ

仕組み

Codemodeエージェントは、複数のツール呼び出しではなく、次のように動作します。

1. 自然言語のタスク（例：「支出の多い上位5人の顧客を見つける」）を受け取ります。
2. そのタスクを達成する完全なGoプログラムを生成します。
3. サンドボックス化されたインタープリター（yaegi）でプログラムを実行します。
4. 結果を返します。

生成されたコードは、データベースツールを呼び出すregistryCall関数にアクセスできます。

package main

import "fmt"

func main() {
    result, err := registryCall("query", map[string]interface{}{
        "sql": `SELECT c.Name, SUM(i.Total) as TotalSpent
                FROM customers c
                JOIN invoices i ON c.CustomerId = i.CustomerId
                GROUP BY c.CustomerId
                ORDER BY TotalSpent DESC
                LIMIT 5`,
    })
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    // Process and format results...
}

コード生成の理由

従来のMCPツール呼び出しでは、LLMとツールサーバーの間で複数の往復が必要です。

LLM → list_tables → result → LLM → get_schema → result → LLM → query → result → LLM

各往復はレイテンシとトークンのオーバーヘッドを追加します。複雑な操作では5〜15回のツール呼び出しが必要になる場合があります。

Codemodeでは、LLMが最初に全体のタスクを考慮し、1つのプログラムを生成します。

LLM → generates code → execute once → result

ベンチマーク結果

複雑な多テーブルクエリ（Chinookデータベース）でのテスト結果は次の通りです。

複雑な分析クエリでは、トークン節約率が83％、レイテンシ削減率が52％に達します。

パッケージ構造

codemode-sqlite-mcp/
├── main.go                 # CLI entry point
├── pkg/
│   ├── executor/           # Sandboxed code execution
│   │   ├── executor.go     # Yaegi interpreter wrapper
│   │   ├── preprocessor.go # Code preprocessing (import fixing, etc.)
│   │   └── errors.go       # Error types
│   ├── validator/          # Security validation
│   │   └── validator.go    # Code safety checks
│   ├── tools/              # SQLite operations
│   │   ├── registry.go     # Tool registry
│   │   ├── tools.go        # Tool implementations
│   │   └── types.go        # Type definitions
│   └── mcp/                # MCP protocol
│       ├── server.go       # Core MCP logic
│       ├── stdio.go        # STDIO transport
│       ├── http.go         # HTTP transport
│       └── types.go        # JSON-RPC types
├── codemode/               # Codemode agent
│   ├── agent.go            # LLM integration
│   └── prompts.go          # System prompts
├── examples/               # Usage examples
│   ├── basic/              # Basic library usage
│   ├── embed-server/       # Embedding MCP server
│   └── custom-executor/    # Custom code execution
└── benchmark/              # Performance testing
    ├── chinook.go          # Chinook database scenarios
    └── runner.go           # Benchmark runner

プログラムによる使用方法

ライブラリとしての使用

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/imran31415/codemode-sqlite-mcp/codemode"
    "github.com/imran31415/codemode-sqlite-mcp/pkg/tools"
)

func main() {
    // Initialize database
    if err := tools.InitDB("./mydata.db"); err != nil {
        log.Fatal(err)
    }
    defer tools.CloseDB()

    // Create tool registry
    registry := tools.NewRegistry()

    // Option 1: Use tools directly
    result, err := registry.Call("list_tables", nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Tables: %v\n", result)

    // Option 2: Use the Codemode agent
    agent := codemode.NewAgent(registry, codemode.AgentConfig{
        APIKey: "your-anthropic-api-key",
    })

    execResult, err := agent.Execute(context.Background(),
        "List all users and count how many are active")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(execResult.Output)
}

カスタムツールの登録

registry := tools.NewRegistry()

// Add a custom tool
registry.Register(&tools.ToolInfo{
    Name:        "custom_analytics",
    Description: "Run custom analytics query",
    Parameters: []tools.ParamInfo{
        {Name: "metric", Type: "string", Required: true},
    },
    Function: func(args map[string]interface{}) (interface{}, error) {
        metric := args["metric"].(string)
        // Custom implementation...
        return result, nil
    },
})

MCPサーバーの埋め込み

package main

import (
    "github.com/imran31415/codemode-sqlite-mcp/pkg/mcp"
    "github.com/imran31415/codemode-sqlite-mcp/pkg/tools"
)

func main() {
    tools.InitDB("./data.db")
    defer tools.CloseDB()

    registry := tools.NewRegistry()
    server := mcp.NewServer(registry)

    // Use STDIO transport (for Claude Desktop integration)
    transport := mcp.NewStdioTransport(server)
    transport.Run()

    // Or use HTTP transport
    // httpTransport := mcp.NewHTTPTransport(server, "8084")
    // httpTransport.Run()
}

エグゼキューター: サンドボックス化されたコード実行

エグゼキューターは、yaegiというGoインタープリターを使用して、LLMが生成したコードを安全に実行します。

• コンパイルステップが不要です。
• 標準ライブラリのアクセスが制限されています。
• データベースアクセス用のシンボルが注入されています。
• 実行タイムアウトを設定できます。
• stdout/stderrがキャプチャされます。

executor := executor.NewExecutor()

// Execute with custom symbols (e.g., database tools)
symbols := map[string]map[string]reflect.Value{
    "tools/tools": {
        "registryCall": reflect.ValueOf(registryCallFunc),
    },
}

result, err := executor.ExecuteWithSymbols(ctx, code, 30*time.Second, symbols)

前処理

エグゼキューターには、次のような前処理機能が含まれています。

1. MarkdownコードブロックからGoコードを抽出します。
2. 欠落しているインポートを自動的に追加します。
3. ツールレジストリシンボルを注入します。
4. 基本的なコード構造を検証します。

CLIリファレンス

codemode-sqlite-mcp [OPTIONS]

OPTIONS:
  --mode=MODE       Server mode: stdio, http, or codemode (default: stdio)
  --port=PORT       HTTP port for http mode (default: 8084)
  --db=PATH         Path to SQLite database (default: codemode.db)
  --api-key=KEY     Anthropic API key (required for codemode mode)
  --model=MODEL     LLM model to use (optional)
  --init-db         Initialize database with sample data and exit
  --help            Show help message

MODES:
  stdio     MCP server with stdio transport (for Claude Desktop)
  http      MCP server with HTTP transport
  codemode  Interactive agent with LLM code generation

依存関係

• yaegi - サンドボックス化された実行用のGoインタープリター
• modernc.org/sqlite - 純粋なGoのSQLite実装（CGO不要）

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

エグゼキューターは、いくつかの安全対策を実装しています。

1. サンドボックス化された実行：コードはインタープリターで実行され、コンパイルされたバイナリとしてではありません。
2. 制限されたインポート：安全な標準ライブラリパッケージのみが利用可能です。
3. 実行タイムアウト：設定可能なタイムアウトで無限ループを防止します。
4. コード検証：実行前に基本的な構造検証を行います。
5. ファイルシステムアクセスなし：生成されたコードは直接ファイルシステムにアクセスできません。

本番環境での使用時には、セキュリティ要件に基づいてバリデータールールの追加レビューをお勧めします。

制限事項

• 生成されたコードは、利用可能な標準ライブラリパッケージに制限されます。
• 複雑なデータ変換には、複数回のLLM試行が必要になる場合があります。
• インタープリターはコンパイルされたGoよりも遅いですが、データベースI/Oに依存するタスクには許容範囲です。
• 現在はAnthropic APIのみをサポートしています（OpenAIサポートは計画中です）。

サンプル

examples/ディレクトリには、実行可能なサンプルが含まれています。

# Basic usage - direct tool calls and Codemode agent
go run ./examples/basic

# Embed MCP server in your own HTTP application
go run ./examples/embed-server

# Custom executor with injected symbols
go run ./examples/custom-executor

ベンチマークの実行

# Build the benchmark tool
go build -o bin/benchmark ./cmd/benchmark/...

# Run Chinook database benchmark
ANTHROPIC_API_KEY="your-key" ./bin/benchmark --mode=chinook

# Run simple comparison benchmark
ANTHROPIC_API_KEY="your-key" ./bin/benchmark --mode=comparison

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

作者

• Imran Hassanali
• Arsheen Ali

連絡先: develop.imran@gmail.com

コントリビューション

コントリビューションは歓迎されます。プルリクエストを送信する前に、重大な変更についてはIssueを開いて議論してください。