quantix-mcp 1.0.0

package/specs/001-mcp-api-integration/data-model.md

@@ -0,0 +1,106 @@
+# Data Model & Schema Mapping
+
+**Feature**: MCP Server for Quantix API Integration
+**Source**: [contracts/openapi.yaml](./contracts/openapi.yaml)
+
+## Domain Entities
+
+### Category
+- **Fields**:
+  - `id`: string (UUID)
+  - `name`: string
+  - `type`: enum ("INCOME", "EXPENSE")
+  - `createdAt`: datetime
+- **Zod Schema**:
+  ```typescript
+  z.object({
+    id: z.string(),
+    name: z.string(),
+    type: z.enum(["INCOME", "EXPENSE"]),
+    createdAt: z.string().datetime()
+  })
+  ```
+
+### Transaction
+- **Fields**:
+  - `id`: string
+  - `type`: enum ("INCOME", "EXPENSE")
+  - `name`: string
+  - `amount`: number (min 0)
+  - `date`: string (YYYY-MM-DD)
+  - `categoryId`: string (optional)
+  - `paymentMethod`: enum ("CASH", "PIX", "DEBIT", "CREDIT") (optional)
+  - `creditCardId`: string (optional, required if CREDIT)
+  - `paid`: boolean (default false)
+- **Zod Schema**:
+  ```typescript
+  z.object({
+    id: z.string(),
+    type: z.enum(["INCOME", "EXPENSE"]),
+    name: z.string(),
+    amount: z.number().min(0),
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+    categoryId: z.string().optional(),
+    paymentMethod: z.enum(["CASH", "PIX", "DEBIT", "CREDIT"]).optional(),
+    creditCardId: z.string().optional(),
+    paid: z.boolean().default(false)
+  })
+  ```
+
+### CreditCard
+- **Fields**:
+  - `id`: string
+  - `name`: string
+  - `limitAmount`: number
+  - `closingDay`: integer (1-31)
+  - `dueDay`: integer (1-31)
+- **Zod Schema**:
+  ```typescript
+  z.object({
+    id: z.string(),
+    name: z.string(),
+    limitAmount: z.number().min(0),
+    closingDay: z.number().int().min(1).max(31),
+    dueDay: z.number().int().min(1).max(31)
+  })
+  ```
+
+## Tool Input Schemas
+
+These schemas define the arguments for the MCP tools.
+
+### `create_category`
+```typescript
+z.object({
+  name: z.string(),
+  type: z.enum(["INCOME", "EXPENSE"])
+})
+```
+
+### `create_transaction`
+```typescript
+z.object({
+  type: z.enum(["INCOME", "EXPENSE"]),
+  name: z.string(),
+  amount: z.number().positive(),
+  date: z.string().describe("ISO date string YYYY-MM-DD"),
+  categoryId: z.string().optional(),
+  paymentMethod: z.enum(["CASH", "PIX", "DEBIT", "CREDIT"]).optional(),
+  creditCardId: z.string().optional()
+})
+```
+
+### `get_transactions`
+```typescript
+z.object({
+  month: z.string().regex(/^\d{4}-\d{2}$/).describe("Format: YYYY-MM")
+})
+```
+
+### `pay_statement`
+```typescript
+z.object({
+  cardId: z.string(),
+  month: z.string().regex(/^\d{4}-\d{2}$/)
+})
+```

package/specs/001-mcp-api-integration/plan.md

@@ -0,0 +1,73 @@
+# Implementation Plan: MCP Server for Quantix API Integration
+
+**Branch**: `001-mcp-api-integration` | **Date**: 2026-01-31 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/001-mcp-api-integration/spec.md`
+
+## Summary
+
+Implement 12 MCP tools to expose the Quantix Personal Finance Manager API capabilities (Categories, Credit Cards, Transactions, Summaries).
+The solution will extend the existing Express-based MCP server in `src/index.ts`, adding Zod validation for all inputs and handling API authentication via `QUANTIX_API_KEY`.
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.9 (Node.js)
+**Primary Dependencies**: `@modelcontextprotocol/sdk`, `express`, `zod`, `fetch` (native Node 18+)
+**Storage**: N/A (Stateless proxy to external API)
+**Testing**: Vitest (Proposed, currently missing in `package.json`)
+**Target Platform**: MCP Clients (e.g., Claude Desktop) connecting via SSE/HTTP
+**Project Type**: Backend / API Proxy
+**Performance Goals**: Low latency proxy (adding <20ms overhead)
+**Constraints**: Must match OpenAPI 3.0 schema strictly for tools.
+**Scale/Scope**: 12 Tools, ~5-6 Service modules.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+*   **Principle 1 (Library-First)**: We will organize tools into modules (`src/tools/`) rather than a monolithic `index.ts`.
+*   **Principle 3 (Test-First)**: We need to introduce a testing framework (`vitest`) as none exists.
+*   **Principle 4 (Integration Testing)**: We will create tests that mock the external API to verify tool behavior.
+
+**Governance**: The `constitution.md` appears to be a template. Proceeding with standard best practices.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-mcp-api-integration/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+└── contracts/           # Phase 1 output (Copy of openapi.yaml)
+```
+
+### Source Code (repository root)
+
+```text
+src/
+├── index.ts                # Entry point (server setup)
+├── config.ts               # Env var loading
+├── tools/                  # New directory for tool definitions
+│   ├── categories.ts       # Category tools
+│   ├── credit-cards.ts     # Credit Card tools
+│   ├── transactions.ts     # Transaction tools
+│   └── summary.ts          # Summary tools
+├── services/               # New directory for API client
+│   └── apiClient.ts        # Typed fetch wrapper for Quantix API
+└── types/                  # Shared types / Zod schemas
+    └── schemas.ts          # Zod schemas matching OpenAPI
+
+tests/                      # New directory
+├── tools/
+│   └── transactions.test.ts
+└── services/
+    └── apiClient.test.ts
+```
+
+**Structure Decision**: Modular approach separating Tool Registration (UI layer) from API Logic (Service layer) and Schemas (Model layer).
+
+## Complexity Tracking
+
+N/A

package/specs/001-mcp-api-integration/quickstart.md

@@ -0,0 +1,74 @@
+# Quickstart: Quantix MCP Server
+
+This guide explains how to configure and run the Quantix MCP server integration.
+
+## Prerequisites
+
+- Node.js 18+
+- A running instance of the Quantix API (or access to Staging/Prod)
+- An API Key for Quantix
+
+## Installation
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Build the project:
+   ```bash
+   npm run build
+   ```
+
+## Configuration
+
+Set the following environment variables. You can add them to a `.env` file or export them in your shell.
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `QUANTIX_API_URL` | Base URL of the Quantix API | `https://api.quantix.example.com` |
+| `QUANTIX_API_KEY` | Your authentication key | `sk_live_12345` |
+| `MPC_PORT` | Port for the MCP server | `3001` (default) |
+
+## Running the Server
+
+### Development Mode
+```bash
+# Windows (PowerShell)
+$env:QUANTIX_API_URL="https://api.quantix.example.com"; $env:QUANTIX_API_KEY="test"; npm run dev
+
+# Linux/Mac
+QUANTIX_API_URL=https://api.quantix.example.com QUANTIX_API_KEY=test npm run dev
+```
+
+### Production
+```bash
+node dist/index.js
+```
+
+## Using with Claude Desktop
+
+Add the server config to your Claude Desktop configuration file:
+
+```json
+{
+  "mcpServers": {
+    "quantix": {
+      "command": "node",
+      "args": ["path/to/morpheus-mcp/dist/index.js"],
+      "env": {
+        "QUANTIX_API_URL": "...",
+        "QUANTIX_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+## Verification
+
+To verify the integration, use the MCP Inspector or curl the running server (since it's HTTP/SSE based):
+
+```bash
+curl http://localhost:3001/mcp
+```

package/specs/001-mcp-api-integration/research.md

@@ -0,0 +1,58 @@
+# Research & Decisions: MCP API Integration
+
+**Feature**: [spec.md](./spec.md)
+**Status**: Complete
+
+## Unknowns & Clarifications
+
+### 1. Project Structure for Scaling Tools
+**Question**: How to manage 12+ tools without bloating `index.ts`?
+**Context**: Current `index.ts` has tool definition inline.
+**Finding**: The MCP SDK `server.registerTool` can be called from imported modules if we pass the `mcpServer` instance, or better yet, we can export `Tool` definitions (name, description, schema, handler) and register them in a loop.
+**Decision**:
+- Create a `registerTools(server: McpServer)` function in each tool module (e.g., `src/tools/categories.ts`).
+- `src/index.ts` will import these registration functions and call them.
+
+### 2. Mocking `fetch` for Tests
+**Question**: Best way to test without hitting real API?
+**Context**: We generally want unit tests to be fast and isolated.
+**Finding**: Since we are using native `fetch` (Node 18+), we can use `vitest` to spy on `global.fetch` or use a library like `msw` (Mock Service Worker). Given the simplicity, basic `vi.spyOn(global, 'fetch')` is sufficient.
+**Decision**: Use `vitest` and spy on `global.fetch`.
+
+## Technology Choices
+
+| Area | Choice | Rationale |
+|------|--------|-----------|
+| **Validation** | `zod` | Native support in MCP SDK, TypeScript native, easy to derive from OpenAPI. |
+| **HTTP Client** | Native `fetch` | No extra dependency weight, fully supported in modern Node. |
+| **Testing** | `vitest` | Fast, compatible with ESM (Type "module" in package.json), Jest-compatible API. |
+| **Env Vars** | `process.env` | Simple standard. |
+
+## Design Patterns
+
+### API Client Wrapper
+Instead of calling `fetch` in every tool, we will create `src/services/apiClient.ts`:
+```typescript
+async function apiFetch<T>(endpoint: string, options: RequestInit): Promise<T> {
+  const url = `${process.env.QUANTIX_API_URL}${endpoint}`;
+  const response = await fetch(url, {
+    ...options,
+    headers: {
+      ...options.headers,
+      'API-KEY': process.env.QUANTIX_API_KEY
+    }
+  });
+  // Error handling logic here
+  return response.json();
+}
+```
+
+### Zod Schema Reusability
+We will define Zod schemas in `src/types/schemas.ts` that mirror the OpenAPI `components/schemas`. Use `z.infer` to generate TypeScript types for compile-time safety.
+
+## Alternatives Considered
+
+- **OpenAPI Code Generator**: Could auto-generate the client.
+  - *Rejected*: Too heavy for 12 endpoints, harder to customize for MCP specific return formats.
+- **Axios**:
+  - *Rejected*: `fetch` is built-in.

package/specs/001-mcp-api-integration/spec.md

@@ -0,0 +1,119 @@
+# Feature Specification: MCP Server for Quantix API Integration
+
+**Feature Branch**: `001-mcp-api-integration`
+**Created**: 2026-01-31
+**Status**: Draft
+**Input**: User description: "Vamos criar um servidor MCP para acessar todas essa rotas da nossa api, coloque o endereço da url como padrão vindo de env e api-key necessária também, use o zod para padronizar e especificar os inputs"
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Configure and Start MCP Server (Priority: P1)
+
+As a developer or AI agent, I want to configure the MCP server with the API URL and API Key so that I can securely access the financial data.
+
+**Why this priority**: Essential for the server to function and authenticate.
+
+**Independent Test**:
+1. Set `QUANTIX_API_URL` and `QUANTIX_API_KEY` environment variables.
+2. Start the server.
+3. Verify that the server starts without errors and is ready to accept requests.
+
+**Acceptance Scenarios**:
+
+1. **Given** valid environment variables, **When** the server starts, **Then** it initializes successfully.
+2. **Given** missing API Key, **When** the server starts, **Then** it might warn or fail calls (depending on implementation), but tools should be registered.
+
+---
+
+### User Story 2 - Manage Financial Categories (Priority: P2)
+
+As a user, I want to create, list, and delete categories to organize my finances.
+
+**Why this priority**: Categories are foundational for transactions.
+
+**Independent Test**: Use an MCP client to call category tools.
+
+**Acceptance Scenarios**:
+
+1. **Given** the MCP server is running, **When** I call `get_categories`, **Then** I receive a list of categories.
+2. **Given** a new category name and type, **When** I call `create_category`, **Then** the category is created via the API.
+3. **Given** a category ID, **When** I call `delete_category`, **Then** the category is removed.
+
+---
+
+### User Story 3 - Manage Credit Cards and Statements (Priority: P2)
+
+As a user, I want to manage credit cards and view/pay statements.
+
+**Why this priority**: Credit card management is a core feature of the API.
+
+**Independent Test**: Call credit card related tools.
+
+**Acceptance Scenarios**:
+
+1. **Given** card details, **When** I call `create_credit_card`, **Then** a new card is added.
+2. **Given** a card ID and month, **When** I call `get_statement`, **Then** I see the transactions for that period.
+3. **Given** a card ID and month, **When** I call `pay_statement`, **Then** the transactions are marked as paid.
+
+---
+
+### User Story 4 - Manage Transactions and Summaries (Priority: P2)
+
+As a user, I want to record transactions and view my monthly financial summary.
+
+**Why this priority**: Core value of a finance manager.
+
+**Independent Test**: Call transaction and summary tools.
+
+**Acceptance Scenarios**:
+
+1. **Given** transaction details, **When** I call `create_transaction`, **Then** it is recorded.
+2. **Given** a month, **When** I call `get_transactions`, **Then** I see the list of transactions.
+3. **Given** a month, **When** I call `get_summary`, **Then** I see income, expenses, and balance.
+4. **Given** a transaction ID, **When** I call `pay_transaction`, **Then** it is marked as paid.
+
+## Functional Requirements
+
+1. **Environment Configuration**:
+   - Support `QUANTIX_API_URL` (defaulting to `https://api.quantix.example.com` or requiring it).
+   - Support `QUANTIX_API_KEY` for authentication header `API-KEY`.
+
+2. **Tool Registration**:
+   - Register the following tools in the MCP server:
+     - `create_category`
+     - `get_categories`
+     - `delete_category`
+     - `create_credit_card`
+     - `get_credit_cards`
+     - `get_statement`
+     - `pay_statement`
+     - `create_transaction`
+     - `get_transactions`
+     - `pay_transaction`
+     - `delete_transaction`
+     - `get_summary`
+
+3. **Input Validation**:
+   - Use `zod` to define input schemas for all tools.
+   - Schemas must match the OpenApi 3.0 definitions provided in `openapi.yaml`.
+
+4. **API Integration**:
+   - Make HTTP requests to the configured `QUANTIX_API_URL`.
+   - Forward the API Key in headers.
+   - Return clear output messages based on API responses.
+
+## Success Criteria
+
+1. **measurable**: 100% of the 12 identified API endpoints are exposed as MCP tools.
+2. **measurable**: Inputs for all tools are validated using Zod schemas.
+3. **verifiable**: The server connects to the backend using the environment variables.
+4. **verifiable**: Tools return meaningful success/error messages to the model.
+
+## Assumptions
+
+- The `openapi.yaml` is the source of truth for schemas.
+- The existing project structure with `src/index.ts` determines the server setup (Express + MCP SDK).
+
+## Clarifications
+
+- None at this stage.

package/specs/001-mcp-api-integration/tasks.md

@@ -0,0 +1,64 @@
+# Tasks: MCP Server for Quantix API Integration
+
+**Spec**: [spec.md](spec.md)
+**Plan**: [plan.md](plan.md)
+**Status**: In Progress
+
+## Phase 1: Setup
+*Goal: Initialize project structure and dependencies*
+
+- [x] T001 [P] Install Vitest and testing dependencies in `package.json`
+- [x] T002 [P] Create project directory structure (`src/tools`, `src/services`, `src/types`, `tests`)
+- [x] T003 Implement `src/config.ts` for environment variable management
+- [x] T004 [P] Configure Vitest in `vitest.config.ts` (or script in package.json)
+
+## Phase 2: Foundational & Shared Components
+*Goal: Establish core API client and data schemas*
+
+- [x] T005 [P] Implement `src/services/apiClient.ts` with authentication and typed `fetch`
+- [x] T006 [P] Implement `src/types/schemas.ts` with Zod definitions for all entities (Category, Transaction, etc.)
+- [x] T007 Create basic test setup/helpers in `tests/setup.ts`
+
+## Phase 3: Server Configuration (User Story 1)
+*Goal: Server starts with correct configuration and tool registration architecture*
+
+- [x] T008 [US1] Refactor `src/index.ts` to use `src/config.ts` and support modular tool registration
+- [x] T009 [US1] Create integration test `tests/server.test.ts` to verify server startup and env handling
+
+## Phase 4: Categories Support (User Story 2)
+*Goal: Enable management of financial categories*
+
+- [x] T010 [US2] TDD: Implement `src/tools/categories.ts` (write tests in `tests/tools/categories.test.ts` first)
+- [x] T011 [US2] Register category tools in `src/index.ts`
+
+## Phase 5: Credit Cards Support (User Story 3)
+*Goal: Enable management of credit cards and statements*
+
+- [x] T012 [US3] TDD: Implement `src/tools/credit-cards.ts` (write tests in `tests/tools/credit-cards.test.ts` first)
+- [x] T013 [US3] Register credit card tools in `src/index.ts`
+
+## Phase 6: Transactions & Summary Support (User Story 4)
+*Goal: Enable transaction recording and financial summaries*
+
+- [x] T014 [US4] TDD: Implement `src/tools/transactions.ts` (write tests in `tests/tools/transactions.test.ts` first)
+- [x] T015 [US4] TDD: Implement `src/tools/summary.ts` (write tests in `tests/tools/summary.test.ts` first)
+- [x] T016 [US4] Register transaction and summary tools in `src/index.ts`
+
+## Phase 7: Polish & Documentation
+*Goal: Final verification and cleanup*
+
+- [x] T017 Remove legacy `get_crypto_price` example from `src/index.ts`
+- [x] T018 Verify `quickstart.md` instructions against the running server
+- [x] T019 Run full test suite and ensure all tests pass
+- [x] T020 Benchmark tool overhead to verify <20ms latency goal
+
+## Dependencies
+
+- Phase 2 depends on Phase 1
+- Phase 3 depends on Phase 2 (config & client)
+- Phase 4, 5, 6 depend on Phase 3 (server setup) and Phase 2 (schemas/client)
+- Phases 4, 5, 6 can be executed in parallel (independent modules), but registered sequentially in T0XX tasks if strictly following order.
+
+## Implementation Strategy
+- **MVP**: Complete through Phase 3 + Phase 4 (Categories) to prove the pattern.
+- **Incremental**: Add Credit Cards and Transactions as separate modules.

package/src/config.ts

@@ -0,0 +1,36 @@
+import 'dotenv/config';
+import * as z from 'zod';
+
+const envSchema = z.object({
+  QUANTIX_API_URL: z.string().default('https://api.quantix.example.com'),
+  QUANTIX_API_KEY: z.string().min(1, "QUANTIX_API_KEY is required"),
+  MCPPORT: z.string().optional().default('3001'),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+});
+
+const processEnv = {
+  QUANTIX_API_URL: process.env.QUANTIX_API_URL,
+  QUANTIX_API_KEY: process.env.QUANTIX_API_KEY,
+  MCPPORT: process.env.MCPPORT,
+  NODE_ENV: process.env.NODE_ENV,
+};
+
+// Parse and validate environment variables
+const parsedEnv = envSchema.safeParse(processEnv);
+
+if (!parsedEnv.success) {
+  console.error("❌ Invalid environment variables:", parsedEnv.error.format());
+  
+  // In a real app, we might want to throw here, but for now we'll just log
+  // and let the application fail when it tries to use the missing keys if essential
+  if (process.env.NODE_ENV !== 'test') {
+      // Allow tests to run without all env vars if they mock config
+  }
+}
+
+export const config = parsedEnv.success ? parsedEnv.data : {
+    QUANTIX_API_URL: process.env.QUANTIX_API_URL || 'https://api.quantix.example.com',
+    QUANTIX_API_KEY: process.env.QUANTIX_API_KEY || 'your_api_key_here',
+    MCPPORT: process.env.MCPPORT || '3001',
+    NODE_ENV: (process.env.NODE_ENV as 'development' | 'production' | 'test') || 'development'
+};

package/src/index.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import express, { type Request, type Response } from 'express';
+import { config } from './config.js';
+import { z } from 'zod';
+import { registerCategoryTools } from './tools/categories.js';
+import { registerCreditCardTools } from './tools/credit-cards.js';
+import { registerTransactionTools } from './tools/transactions.js';
+import { registerSummaryTools } from './tools/summary.js';
+import { registerAccountTools } from './tools/accounts.js';
+import { registerSettingsTools } from './tools/settings.js';
+
+export function getServer() {
+    const mcpServer = new McpServer({
+        name: 'quantix_mcp_server',
+        version: '1.0.0'
+    });
+
+    console.log('McpServer started');
+
+    // Register Tools here
+    registerCategoryTools(mcpServer);
+    registerCreditCardTools(mcpServer);
+    registerTransactionTools(mcpServer);
+    registerSummaryTools(mcpServer);
+    registerAccountTools(mcpServer);
+    registerSettingsTools(mcpServer);
+
+    return mcpServer;
+}
+
+const app = express();
+app.use(express.json());
+
+app.post('/mcp', async (req: Request, res: Response) => {
+    const mcpServer = getServer();
+
+    const transport = new StreamableHTTPServerTransport({
+    });
+    const mcpTransport = transport as unknown as Transport;
+
+    res.on('close', () => {
+        transport.close();
+        mcpServer.close();
+    });
+
+    await mcpServer.connect(mcpTransport);
+    await transport.handleRequest(req, res, req.body);
+});
+
+if (config.NODE_ENV !== 'test') {
+    const MCPPORT = config.MCPPORT;
+    app.listen(MCPPORT, () => {
+        console.log(`MCP server is running on http://localhost:${MCPPORT}/mcp`);
+    });
+}
+
+export { app };

package/src/services/apiClient.ts

@@ -0,0 +1,49 @@
+import { config } from '../config.js';
+
+export class ApiClientError extends Error {
+  constructor(public message: string, public status: number, public statusText: string) {
+    super(message);
+    this.name = 'ApiClientError';
+  }
+}
+
+async function apiFetch<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+  const url = `${config.QUANTIX_API_URL}${endpoint}`;
+  
+  const headers = {
+    'Content-Type': 'application/json',
+    'x-api-key': config.QUANTIX_API_KEY,
+    ...options.headers,
+  };
+
+  const response = await fetch(url, {
+    ...options,
+    headers,
+  });
+
+  if (!response.ok) {
+    throw new ApiClientError(
+      `API request failed: ${response.status} ${response.statusText}`,
+      response.status,
+      response.statusText
+    );
+  }
+
+  // Handle 204 No Content
+  if (response.status === 204) {
+    return {} as T;
+  }
+
+  return response.json();
+}
+
+export const apiClient = {
+  get: <T>(endpoint: string) => apiFetch<T>(endpoint, { method: 'GET' }),
+  post: <T>(endpoint: string, body: unknown) => 
+    apiFetch<T>(endpoint, { method: 'POST', body: JSON.stringify(body) }),
+  patch: <T>(endpoint: string, body: unknown = {}) => 
+    apiFetch<T>(endpoint, { method: 'PATCH', body: JSON.stringify(body) }),
+  put: <T>(endpoint: string, body: unknown) => 
+    apiFetch<T>(endpoint, { method: 'PUT', body: JSON.stringify(body) }),
+  delete: <T>(endpoint: string) => apiFetch<T>(endpoint, { method: 'DELETE' }),
+};