社内勉強会の発表資料用の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等）の設定ファイルに以下を追加：

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

2. **使用例**

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

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

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

### 直接実行する場合

1. **ビルド**
   ```bash
   cargo build --release
   ```

2. **実行**
   ```bash
   ./target/release/smaregi-mcp
   ```

## 開発者向け情報

### プロジェクト構造

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

### 開発に参加する

1. **仕様の確認**
   - [要件定義](.kiro/specs/smaregi-mcp-poc/requirements.md)
   - [技術設計](.kiro/specs/smaregi-mcp-poc/design.md)
   - [実装計画](docs/implementation-plan.md)

2. **実装の開始**
   - [タスクリスト](.kiro/specs/smaregi-mcp-poc/tasks.md)を確認
   - 順次タスクを実行

3. **MCPについて学ぶ**
   - [MCP概要](docs/mcp-overview.md)
   - [MCP公式ドキュメント](https://modelcontextprotocol.io/)

### MCP Inspectorによる動作確認

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

#### インストール

```bash
npm install -g @modelcontextprotocol/inspector
```

#### 基本的な使い方

```bash
# 開発中（デバッグビルド）
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](https://modelcontextprotocol.io/)
- [スマレジプラットフォームAPI](https://developers.smaregi.dev/platform-api-reference/)
- [MCP Rust SDK](https://github.com/modelcontextprotocol/rust-sdk)

## サポート

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