smart-ai-bridge: Instructions file for Codex

AGENTS.md — Smart AI Bridge

Instructions for AI agents and agentic harnesses. Two audiences, in order:

1. Consuming this project — installing and running it as an MCP server. Start here.
2. Working on this repo — where code lives and what the hard rules are.

Everything below is verified against the code at v2.15.0. If something here disagrees with the code, the code wins and this file is a bug.

---

Part 1 — Install and run (for a harness onboarding this as a tool)

What this is

An MCP server (stdio transport, ESM Node.js) that gives an MCP client 17 tools for token-saving file operations, multi-AI orchestration, and code review. It routes each request across local and cloud LLM backends.

Requirements

• Node.js >= 18.0.0 (enforced via engines in package.json)
• An MCP client that speaks stdio
• No API key is required to install, start, or list tools. A backend is only needed to actually execute a tool call.

Install

There is no npm package. Install by cloning:

git clone https://github.com/Platano78/smart-ai-bridge.git
cd smart-ai-bridge
npm install
npm test          # expect all tests passing, 0 failures

Run

node /absolute/path/to/smart-ai-bridge/src/server.js

• stdout carries MCP JSON-RPC only. Never write to stdout from this codebase; it corrupts the protocol stream. All diagnostics go to stderr.
• The server starts and serves tools/list (17 tools) with no backends configured.
• On startup it runs a readiness audit to stderr. A backend whose key is unset is reported as cannot verify — <KEY> not set. That is not an error and not a failed install.

Register with a client

Use an absolute path; relative paths depend on the client honoring cwd. Copy .mcp.json.example, or:

{
  "mcpServers": {
    "smart-ai-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/smart-ai-bridge/src/server.js"],
      "env": { "NVIDIA_API_KEY": "your-key" }
    }
  }
}