社内勉強会の発表資料用のMCPサーバ試作レポジトリです。

---

スマレジMCPサーバー

スマレジプラットフォームAPIの操作方法を提供するModel Context Protocol (MCP) サーバーです。

概要

このMCPサーバーは、LLM（Claude、GPT等）がスマレジAPIを使用するコードを生成できるよう、API操作方法の情報を提供します。実際のAPIを呼び出すのではなく、APIの使用方法を教えるドキュメントサーバーとして機能します。

機能

提供するリソース

1. 取引一覧取得方法 (smaregi://api/transactions/list)

   • スマレジAPIから取引一覧を取得する方法
   • エンドポイント、パラメータ、サンプルコードを含む

2. 取引作成方法 (smaregi://api/transactions/create)

   • スマレジAPIで新規取引を作成する方法
   • 必須フィールド、リクエスト形式、サンプルコードを含む

特徴

• 動的ドキュメント取得: 最新のスマレジAPIドキュメントを都度取得
• MCP準拠: 標準的なMCPプロトコルに完全準拠
• Docker対応: コンテナとして簡単にデプロイ可能
• STDIO Transport: 標準入出力による安全な通信

必要な環境

• Docker（推奨）
• または Rust 1.75以上（直接実行する場合）

インストールと使用方法

Dockerを使用する場合（推奨）

1. MCPクライアント設定

   MCPクライアント（Claude Desktop等）の設定ファイルに以下を追加：

   {
     "mcpServers": {
       "smaregi": {
         "command": "docker",
         "args": ["run", "--rm", "-i", "smaregi-mcp:latest"]
       }
     }
   }
   

2. 使用例

   MCPクライアントで以下のように質問できます：

   スマレジAPIで取引一覧を取得するコードを書いて
   

   スマレジAPIで新しい取引を作成するPythonコードを教えて
   

直接実行する場合

1. ビルド

   cargo build --release
   

2. 実行

   ./target/release/smaregi-mcp
   

開発者向け情報

プロジェクト構造

• .kiro/specs/: プロジェクト仕様（要件、設計、タスク）
• docs/: 技術ドキュメント
• src/: Rustソースコード（実装後）

開発に参加する

1. 仕様の確認

   • 要件定義
   • 技術設計
   • 実装計画

2. 実装の開始

   • タスクリストを確認
   • 順次タスクを実行

3. MCPについて学ぶ

   • MCP概要
   • MCP公式ドキュメント

MCP Inspectorによる動作確認

開発中のMCPサーバーの動作確認には、公式のMCP Inspectorを使用します。

インストール

npm install -g @modelcontextprotocol/inspector

基本的な使い方

# 開発中（デバッグビルド）
mcp-inspector cargo run

# リリースビルド
cargo build --release
mcp-inspector ./target/release/smaregi-mcp

# Docker環境
docker build -t smaregi-mcp:latest .
mcp-inspector docker run -i smaregi-mcp:latest

確認項目

• サーバーが正常に起動するか
• リソース一覧が正しく表示されるか（Resources Tab）
• 各リソースの内容が取得できるか
• エラーハンドリングが適切か
• ログ出力が正しく動作するか

注意事項

• Inspectorの後にコマンド全体をそのまま渡す（--は不要）
• STDIO方式のサーバーでは標準出力に書き込まない（JSON-RPCが破壊される）
• ログはstderrに出力する

技術仕様

• 言語: Rust
• MCPプロトコル: JSON-RPC 2.0 over STDIO
• アーキテクチャ: 4層構造（Transport → Protocol → Resource → Application）
• ドキュメントソース: https://developers.smaregi.dev/platform-api-reference/

制限事項

• 実際のスマレジAPIは呼び出しません
• 認証機能は提供しません
• データの保存やキャッシュは行いません
• 取引一覧取得と作成のみをサポート（PoC範囲）

ライセンス

このプロジェクトはProof of Conceptとして作成されています。

参考資料

• Model Context Protocol
• スマレジプラットフォームAPI
• MCP Rust SDK

サポート

技術的な質問や問題については、プロジェクトの仕様ドキュメントを参照してください。