CONTRIBUTING.md

Contributing to bank-mcp

Adding a New Provider

The most impactful contribution is adding support for a new banking API.

Steps

1. Create the provider directory: src/providers/your-provider/

2. Implement the provider class (index.ts):

import { BankProvider } from "../base.js";
import type { BankAccount, Transaction, Balance, TransactionFilter, ConfigField } from "../../types.js";

export class YourProvider extends BankProvider {
  readonly name = "your-provider";
  readonly displayName = "Your Bank Service";

  validateConfig(config: Record<string, unknown>): void {
    // Check required fields exist
  }

  getConfigSchema(): ConfigField[] {
    return [
      { name: "apiKey", label: "API Key", type: "string", required: true, secret: true },
    ];
  }

  async listAccounts(config: Record<string, unknown>): Promise<BankAccount[]> {
    // Call your API, map to BankAccount[]
  }

  async listTransactions(
    config: Record<string, unknown>,
    accountId: string,
    filter?: TransactionFilter,
  ): Promise<Transaction[]> {
    // Fetch & normalize transactions
  }

  async getBalance(
    config: Record<string, unknown>,
    accountId: string,
  ): Promise<Balance[]> {
    // Fetch & normalize balances
  }
}

3. Register it in src/providers/registry.ts:

import { YourProvider } from "./your-provider/index.js";
register(new YourProvider());

4. Add tests with mocked HTTP responses in tests/unit/providers/your-provider.test.ts

5. Add fixtures — sanitized API responses in tests/fixtures/your-provider/

Key principles

• Normalize everything — map provider-specific fields to the standard Transaction, Balance, BankAccount types
• Handle pagination — fetch all pages before returning
• Amount signs — expenses should be negative, income positive
• Description — use the most human-readable field as description, raw data in reference
• No new dependencies unless absolutely necessary — use the httpFetch utility

Running tests

npm test                    # All tests
npm test -- --watch         # Watch mode
npm test -- --reporter=verbose  # Detailed output

Code style

• TypeScript strict mode
• ESM imports (.js extensions in import paths)
• No classes where functions suffice
• Errors as structured JSON in tool responses (not thrown MCP errors)

Bug Reports & Feature Requests

Open an issue on GitHub with:

• What you expected
• What happened
• Steps to reproduce
• Provider name (if relevant)