Zaim API

Um modelo de servidor para interagir com APIs que exigem uma chave de API, usando a Zaim API como exemplo.

Documentação

Servidor MCP da API Zaim

Este é um servidor MCP (Model Context Protocol) que permite a integração com a API Zaim. Utiliza autenticação OAuth 1.0a para obter e manipular dados de contabilidade doméstica do Zaim.

Características

Integração completa com a API Zaim (OAuth 1.0a)
Conjunto abrangente de 14 ferramentas
Obtenção, criação, atualização e exclusão de dados de contabilidade doméstica
Obtenção de dados mestre (categorias, gêneros, contas, moedas)
Implementação type-safe baseada em TypeScript
Validação rigorosa com esquemas Zod
Cobertura abrangente de testes (128 testes)
Suporte a Docker

Ferramentas implementadas

Autenticação e informações do usuário

zaim_check_auth_status - Verificação do estado de autenticação
zaim_get_user_info - Obtenção de informações do usuário

Operações de dados de contabilidade doméstica

zaim_get_money_records - Obtenção de registros de contabilidade doméstica (com suporte a filtragem e paginação)
zaim_create_payment - Criação de registros de despesas
zaim_create_income - Criação de registros de receitas
zaim_create_transfer - Criação de registros de transferência
zaim_update_money_record - Atualização de registros existentes
zaim_delete_money_record - Exclusão de registros

Obtenção de dados mestre

zaim_get_user_categories - Lista de categorias do usuário
zaim_get_user_genres - Lista de gêneros do usuário
zaim_get_user_accounts - Lista de contas do usuário
zaim_get_default_categories - Lista de categorias padrão
zaim_get_default_genres - Lista de gêneros padrão
zaim_get_currencies - Lista de moedas disponíveis

Requisitos

Docker (recomendado)
Node.js 22+ (para desenvolvimento local)
Credenciais de autenticação OAuth da API Zaim
- Consumer Key
- Consumer Secret
- Access Token
- Access Token Secret

Configuração de variáveis de ambiente

# 必須：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

Instalação

Usando Docker (recomendado)

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

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

Desenvolvimento local

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

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

# テスト実行
npm test

# ビルド
npm run build

Configuração do Claude Desktop

1. Localização do arquivo de configuração

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

2. Configuração 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. Configuração de build 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"
      }
    }
  }
}

Exemplos de uso

Verificação do estado de autenticação

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

Obtenção de dados de contabilidade doméstica

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

Registro de despesas

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

Obtenção da lista de categorias

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

Configuração da API

Configurações detalhadas estão disponíveis em config/zaim-config.json:

Configuração de timeout da API
Configuração de limite de taxa
Configuração de cache
Configuração de nível de log

Estrutura do projeto

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設定

Guia de desenvolvimento

Fluxo de trabalho Git

Crie um branch para cada funcionalidade
Implemente com TDD (desenvolvimento orientado a testes)
Verifique se todos os testes passam
Crie um pull request

Convenção de mensagens de commit

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

Scripts disponíveis

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起動

Solução de problemas

Erros de autenticação

Verifique se as variáveis de ambiente estão configuradas corretamente
Verifique as configurações do aplicativo no site de desenvolvedores do Zaim
Verifique a validade do token de acesso

Problemas relacionados ao Docker

Verifique se o daemon do Docker está em execução
Verifique se as variáveis de ambiente estão sendo passadas corretamente
Verifique as mensagens de erro detalhadas nos logs

Contribuição

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feat/amazing-feature)
Faça commit das alterações (git commit -m 'feat: 素晴らしい機能を追加')
Envie o branch (git push origin feat/amazing-feature)
Crie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.