npm package: @fipto/mcp-fipto
Description: This project implements a Model Context Protocol (MCP) server for interacting with the Fipto API. It allows MCP-compatible clients to leverage Fipto functionalities through a standardized set of tools.
Author: Stéphane KLEIN
Latest version: 1.0.3

# Fipto MCP Server

This project implements a Model Context Protocol (MCP) server for interacting with the Fipto API. It allows MCP-compatible clients to leverage Fipto functionalities through a standardized set of tools.

The core logic for the server is implemented in [`src/index.ts`](src/index.ts).

## Prerequisites

- Node.js (version compatible with ESM and top-level await, e.g., >=16.x)
- NPM or Yarn for managing dependencies.
- Access credentials and endpoint for a Fipto API instance.

## Configuration

The server requires the following environment variables to be set:

- `BASE_URL`: The base URL of the Fipto API.
- `USER_ID`: The User ID for authenticating with the Fipto API.
- `PRIVATE_KEY`: The private key associated with the `USER_ID` for signing API requests.

You can set these variables in your environment or use a `.env` file (e.g., by using a library like `dotenv`).

## Running the Server

The server is designed to communicate over standard input/output (stdio) using `StdioServerTransport` from the MCP SDK.

Once transpiled with `tsc`, it can be run with

```bash
node dist/index.js
```

An MCP client will typically manage the execution of this command.

## Provided Tools

The Fipto MCP server exposes the following tools:

### 1. `list_my_companies`

- **Description**: Lists all companies the current user is a member of at Fipto.
- **Parameters**: None.
- **Returns**: A JSON object containing an array of company objects, each with details such as company ID, name, and membership role.

### 2. `list_company_wallets`

- **Description**: Lists all wallets for a specific company at Fipto.
- **Parameters**:
  - `company_id` (string, UUID): The UUID of the company.
- **Returns**: A JSON object containing an array of wallet objects, each with details such as wallet ID, name, asset, and balance.

### 3. `list_company_transactions`

- **Description**: Lists all transactions for a specific company at Fipto. Supports various filters.
- **Parameters**:
  - `company_id` (string, UUID): The UUID of the company.
  - `transaction_types` (array of strings, optional): Filter by transaction types (e.g., "payin", "payout").
  - `asset_types` (array of strings, optional): Filter by asset types.
  - `page_number` (number, optional): For pagination.
  - `page_size` (number, optional): For pagination.
  - `sort` (string, optional): Sorting criteria.
  - `wallet_id` (string, UUID, optional): Filter by a specific wallet ID.
  - `statuses` (array of strings, optional): Filter by transaction statuses.
  - `can_be_signed_by` (string, UUID, optional): Filter by transactions that can be signed by a specific user ID.
- **Returns**: A polymorphic array of transaction objects (each with a 'type' discriminator) that include common fields plus type‑specific attributes.

## Usage with MCP Clients

This server can be integrated with any MCP-compatible client, such as the Model Context Protocol extension in VS Code. To use it, you would typically configure the client to run the server command (e.g., `node dist/index.js` or `npx ts-node src/index.ts`) and provide the necessary environment variables.

Refer to the documentation of your specific MCP client for instructions on adding and configuring custom MCP servers.

The following is an example of how it would like in VS Code (`.vscode/mcp.json`):

```json
{
  "mcp": {
    "servers": {
      "fipto": {
        "command": "npx",
        "args": ["-y", "@fipto/mcp-fipto"],
        "env": {
          "BASE_URL": "https://api.fipto.app",
          "USER_ID": "abcd1234-41d3-4ca3-b191-930357973603",
          "PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADAN....\n-----END PRIVATE KEY-----"
        }
      }
    }
  }
}
```