Zaim API

Una plantilla de servidor para interactuar con APIs que requieren una clave de API, usando la API de Zaim como ejemplo.

GitHub
8
Prueba este MCPPatrocinado

Documentación

Servidor MCP de la API de Zaim

README en inglés

Este es un servidor MCP (Protocolo de Contexto de Modelo) que permite la integración con la API de Zaim. Utiliza autenticación OAuth 1.0a para recuperar y manipular los datos de contabilidad personal de Zaim.

Características

  • Integración completa con la API de Zaim (OAuth 1.0a)
  • Conjunto integral de 14 herramientas
  • Recuperación, creación, actualización y eliminación de datos de contabilidad personal
  • Recuperación de datos maestros (categorías, géneros, cuentas, monedas)
  • Implementación tipada y segura basada en TypeScript
  • Validación estricta mediante esquemas Zod
  • Cobertura integral de pruebas (128 pruebas)
  • Soporte para Docker

Herramientas implementadas

Autenticación e información del usuario

  • zaim_check_auth_status - Verificación del estado de autenticación
  • zaim_get_user_info - Recuperación de información del usuario

Operaciones con datos de contabilidad personal

  • zaim_get_money_records - Recuperación de registros de contabilidad personal (con filtrado y paginación)
  • zaim_create_payment - Creación de registros de gastos
  • zaim_create_income - Creación de registros de ingresos
  • zaim_create_transfer - Creación de registros de transferencias
  • zaim_update_money_record - Actualización de registros existentes
  • zaim_delete_money_record - Eliminación de registros

Recuperación de datos maestros

  • zaim_get_user_categories - Lista de categorías del usuario
  • zaim_get_user_genres - Lista de géneros del usuario
  • zaim_get_user_accounts - Lista de cuentas del usuario
  • zaim_get_default_categories - Lista de categorías predeterminadas
  • zaim_get_default_genres - Lista de géneros predeterminados
  • zaim_get_currencies - Lista de monedas disponibles

Requisitos

  • Docker (recomendado)
  • Node.js 22+ (para desarrollo local)
  • Credenciales de autenticación OAuth de la API de Zaim
    • Clave de consumidor
    • Secreto de consumidor
    • Token de acceso
    • Secreto del token de acceso

Configuración de variables de entorno

# 必須：Zaim API認証情報
ZAIM_CONSUMER_KEY=your_consumer_key
ZAIM_CONSUMER_SECRET=your_consumer_secret
ZAIM_ACCESS_TOKEN=your_access_token
ZAIM_ACCESS_TOKEN_SECRET=your_access_token_secret

Instalación

Uso con Docker (recomendado)

# リポジトリをクローン
git clone https://github.com/yone-k/zaim-api-mcp.git
cd zaim-api-mcp

# Dockerイメージをビルド
docker build -t zaim-api-mcp .

Desarrollo local

# 依存関係をインストール
npm install

# 開発モードで開始
npm run dev

# テスト実行
npm test

# ビルド
npm run build

Configuración de Claude Desktop

1. Ubicación del archivo de configuración

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Configuración de Docker (recomendado)

{
  "mcpServers": {
    "zaim-api": {
      "command": "docker",
      "args": [
        "run", 
        "--rm", 
        "-i",
        "-e", "ZAIM_CONSUMER_KEY=your_consumer_key",
        "-e", "ZAIM_CONSUMER_SECRET=your_consumer_secret",
        "-e", "ZAIM_ACCESS_TOKEN=your_access_token",
        "-e", "ZAIM_ACCESS_TOKEN_SECRET=your_access_token_secret",
        "zaim-api-mcp"
      ]
    }
  }
}

3. Configuración de compilación local

{
  "mcpServers": {
    "zaim-api": {
      "command": "node",
      "args": ["/path/to/zaim-api-mcp/dist/index.js"],
      "env": {
        "ZAIM_CONSUMER_KEY": "your_consumer_key",
        "ZAIM_CONSUMER_SECRET": "your_consumer_secret",
        "ZAIM_ACCESS_TOKEN": "your_access_token",
        "ZAIM_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

Ejemplos de uso

Verificación del estado de autenticación

zaim_check_auth_status を使って認証が正しく設定されているか確認してください

Recuperación de datos de contabilidad personal

zaim_get_money_records を使って、2024年1月の支出記録を取得してください

Registro de gastos

zaim_create_payment を使って、本日1,500円の昼食代を食費カテゴリで記録してください

Recuperación de la lista de categorías

zaim_get_user_categories を使って利用可能なカテゴリ一覧を表示してください

Configuración de la API

Se puede configurar en detalle con config/zaim-config.json:

  • Configuración de tiempo de espera de la API
  • Configuración de límite de velocidad
  • Configuración de caché
  • Configuración del nivel de registro

Estructura del proyecto

zaim-api-mcp/
├── src/
│   ├── core/              # MCPサーバーコア機能
│   │   ├── tool-handler.ts
│   │   └── zaim-api-client.ts
│   ├── tools/             # ツール実装
│   │   ├── auth/          # 認証関連ツール
│   │   ├── money/         # 家計簿データツール
│   │   ├── master/        # マスターデータツール
│   │   └── registry.ts    # ツール登録
│   ├── types/             # 型定義
│   ├── utils/             # ユーティリティ
│   └── index.ts           # エントリーポイント
├── tests/                 # テストファイル
├── config/                # 設定ファイル
└── docker-compose.yml     # Docker設定

Guía de desarrollo

Flujo de trabajo con Git

  1. Crear una rama para cada funcionalidad
  2. Implementar con TDD (desarrollo guiado por pruebas)
  3. Confirmar que todas las pruebas pasen
  4. Crear una solicitud de extracción

Convenciones para mensajes de confirmación

feat: 新機能の追加
fix: バグ修正
docs: ドキュメントの変更
refactor: リファクタリング
test: テストの追加・修正
chore: ビルドプロセスやツールの変更

Scripts disponibles

npm run build          # TypeScriptビルド
npm run start          # 本番サーバー起動
npm run dev            # 開発サーバー起動
npm run lint           # ESLint実行
npm run typecheck      # 型チェック
npm test               # テスト実行
npm run test:watch     # テスト監視モード
npm run test:coverage  # カバレッジレポート
npm run docker:build   # Dockerイメージビルド
npm run docker:run     # Dockerコンテナ実行
npm run docker:dev     # Docker Compose起動

Solución de problemas

Errores de autenticación

  • Verificar que las variables de entorno estén configuradas correctamente
  • Verificar la configuración de la aplicación en el sitio de desarrolladores de Zaim
  • Verificar la fecha de vencimiento del token de acceso

Problemas relacionados con Docker

  • Verificar que el demonio de Docker esté en ejecución
  • Verificar que las variables de entorno se pasen correctamente
  • Verificar los mensajes de error detallados en los registros

Contribuciones

  1. Hacer un fork del repositorio
  2. Crear una rama de funcionalidad (git checkout -b feat/amazing-feature)
  3. Confirmar los cambios (git commit -m 'feat: 素晴らしい機能を追加')
  4. Enviar la rama (git push origin feat/amazing-feature)
  5. Crear una solicitud de extracción

Licencia

Licencia MIT: consulte el archivo LICENCIA para obtener más detalles.

Enlaces relacionados