API

Simple api for small applications using express, jsonwebtoken, sequelize and websocket

Installation

The module is now available on npm! npm i @andrewcaires/api

Example usage

// .env

NODE_ENV=development

DATABASE_URI=mariadb://root:root@localhost:3306/database
DATABASE_LOG=false

HTTP_PORT=3000
HTTP_PATH=/api
HTTP_PUBLIC=/public
HTTP_CROSS=true

// HTTP_TLS_CRT=./ssl/http.crt
// HTTP_TLS_KEY=./ssl/http.key

TOKEN_SECRET=change-me-to-a-long-random-secret
TOKEN_TTL=1d
TOKEN_TTL_RENEW=1d
TOKEN_COOKIE=authorization
TOKEN_COOKIE_SET=true
TOKEN_HEADER=authorization
TOKEN_TYPE=bearer

API_WEBSOCKET_START=false

// index.ts

import {

  Application,

  AuthController,
  GroupController,
  GroupRouteController,
  LogsController,
  RouteController,
  UserController,
  UserGroupController,

} from "@andrewcaires/api";

const main = async () => {

  const app = new Application(
    [

      new AuthController,
      new GroupController,
      new GroupRouteController,
      new LogsController,
      new RouteController,
      new UserController,
      new UserGroupController,

    ]
  );

  await app.run();

};

main().catch(console.log);

Workers

Use @Worker em um metodo de controller carregado pela aplicação e inicie o processo com app.run(). Sem --worker, app.run() inicia a API normalmente; com --worker, ele prepara banco, migrations e sync() dos controllers, executa o worker e nao abre a porta HTTP.

import { BaseController, Worker } from "@andrewcaires/api";

class ReportsController extends BaseController {

  @Worker("reports.daily")
  protected async daily() {

    return { ok: true };
  }
}

node dist/index.js --worker reports.daily

MCP Streamable HTTP

McpController exposes /mcp for MCP Streamable HTTP using protocol 2025-11-25 by default. Clients must call initialize, send notifications/initialized, and then include MCP-Session-Id and MCP-Protocol-Version on subsequent requests. The server also keeps compatibility with 2025-06-18 when that version is requested during initialization.

The Streamable HTTP transport supports POST for JSON-RPC calls, DELETE to close a session, and OPTIONS for preflight. GET and HEAD return 405 Method Not Allowed; the older HTTP+SSE transport is not implemented. Invalid JSON bodies return a JSON-RPC parse error (-32700) with id: null.

Implemented MCP capabilities:

• Tools via @McpTool, tools/list, and tools/call.
• Tool input and output schemas generated from @andrewcaires/utils.js validations.
• Tool input validation failures return a tools/call result with isError: true; protocol errors such as invalid sessions or missing tool names still return JSON-RPC errors.

Not implemented by this package: resources, prompts, elicitation, sampling, OAuth authorization endpoints, tasks, and SSE streaming.

Configuration:

MCP_ALLOWED_ORIGINS=https://app.example.com
MCP_RATE_LIMIT_MAX=120
MCP_RATE_LIMIT_WINDOW=1m
MCP_SESSION_TTL=30m

Tools can be declared from any loaded controller:

import { Validation } from "@andrewcaires/utils.js";
import { McpTool } from "@andrewcaires/api";

class UsersController {

  @McpTool({
    name: "users.search",
    title: "Search users",
    description: "Searches users by text.",
    input: {
      q: Validation.string().required().description("Search text."),
      active: Validation.boolean().parse().empty(false).description("Filter only active users."),
    },
    output: {
      total: Validation.number().required().description("Total matched users."),
    },
  })
  protected async searchUsers(args, context) {

    return {
      total: 0,
    };
  }
}

Links

• Docs
• npm

License

• MIT