Neoact (neoact)

Standalone command-line tool bridge for third-party services via Composio API v3.1, exposing tools across CLI, HTTP, and Model Context Protocol (MCP).

Features

• 🛠 CLI-First: Manage accounts, connections, and tool executions directly from the terminal.
• ⚡ Zero-SDK Requirement: Works as an ordinary Unix-style standalone binary (neoact).
• 📁 Isolated Local State: Credentials (credentials.json), configuration (config.json), and tool cache (tools/<toolkit>.json) stored locally in ~/.neoact/ (or configurable via NEOACT_HOME).
• 🔌 Unified Runtime: Tools connected through CLI are immediately available via HTTP and standard MCP stdio.
• 🔍 Fast Local Search: Tokenized and ranked search across cached tools with zero external network requests.
• 🔒 Security First: Default loopback binding (127.0.0.1), secret sanitization across logs and outputs, and bearer token protection.

Installation

npm install -g neoact

Or run directly with npx:

npx neoact <command>

Quickstart

1. Initialize Account

Provision a dedicated Composio account:

neoact init

Or import an existing Composio API key:

neoact init --api-key ak_...

Check status:

neoact status

2. Connect Toolkits

Managed OAuth (e.g. Gmail, GitHub):

neoact connect gmail

API Key or Credentials:

neoact connect perplexityai --credential generic_api_key=pplx_...

No-Auth Toolkits:

neoact connect hackernews

3. Sync Tools

neoact sync gmail

Or sync all active connections:

neoact sync --all

4. Search and Inspect Tools

Search tools locally:

neoact tools search "send an email"

Inspect input schema:

neoact tools schema GMAIL_SEND_EMAIL

5. Execute Tools

Direct argument JSON:

neoact tools call GMAIL_SEND_EMAIL \
  --args '{"recipient_email":"[email protected]","subject":"Hello","body":"Hi"}'

Or from a file:

neoact tools call GMAIL_SEND_EMAIL --args-file ./args.json

Or through standard input:

echo '{"query":"neoact"}' | neoact tools call GITHUB_SEARCH_REPOSITORIES --stdin

Expose as Servers

Model Context Protocol (MCP)

Start the standard MCP stdio server:

neoact serve mcp

Add to your MCP client configuration (e.g., Claude Desktop, Cursor, Antigravity):

{
  "mcpServers": {
    "neoact": {
      "command": "neoact",
      "args": ["serve", "mcp"]
    }
  }
}

HTTP REST Server

Start the local HTTP REST server (default http://127.0.0.1:7337):

neoact serve http

Options:

neoact serve http --port 8080 --token ntb_secret_token

HTTP Routes

| Method | Endpoint | Description | |---|---|---| | GET | /health | Server health check | | GET | /status | Runtime status | | GET | /connections | List live connected accounts | | POST | /connections | Connect a toolkit | | DELETE | /connections/:id | Revoke/delete a connection | | GET | /toolkits/:slug | Inspect toolkit | | POST | /toolkits/:slug/sync | Sync toolkit tools | | GET | /tools | List cached tools (optional ?toolkit=) | | GET | /tools/:slug | Get tool metadata and schema | | POST | /tools/search | Search tools ({ "query": "...", "limit": 5 }) | | POST | /tools/:slug/call | Execute tool ({ "args": { ... } }) |

Configuration & Environment Variables

Priority order: CLI Flags > Environment Variables > ~/.neoact/config.json

| Environment Variable | Description | Default | |---|---|---| | NEOACT_HOME | State directory path | ~/.neoact/ | | NEOACT_API_KEY | Composio API Key override | Loaded from credentials.json | | NEOACT_HOST | HTTP server default bind host | 127.0.0.1 | | NEOACT_PORT | HTTP server default port | 7337 | | NEOACT_SERVER_TOKEN | Bearer token for HTTP authentication | None |

Note: Legacy NEOIST_TOOLS_* environment variables continue to be supported as fallbacks.

Exit Codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | General failure | | 2 | Invalid command or arguments | | 3 | Not initialized | | 4 | Not connected | | 5 | Toolkit/Tool not found | | 6 | Authentication or connection failure | | 7 | Upstream rate limit | | 8 | Upstream API failure |

License

MIT