io.github.PritaS/actionforge
MCP server for ActionForge: expose your account's tools to Claude and any MCP client.
Open source Open in the app JSON README (API)
About
MCP server for ActionForge: expose your account's tools to Claude and any MCP client.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- pritas
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.3
- Last push
- 2026-08-20T16:46:01Z
- Repository state
- ativo
- Language
- TypeScript
- License
- ISC
- Added
- 2026-08-29 03:02:10
- Updated
- 2026-08-29 03:02:10
- Origin id
io.github.PritaS/actionforge
README
# ActionForge MCP server
[](https://www.npmjs.com/package/actionforge-mcp)
Publishes an [ActionForge](https://pritas.github.io/actionforge_ui/) account's
tools to any MCP client — Claude Desktop, Claude Code, or anything else speaking
the Model Context Protocol.
**ActionForge** turns a description and a pair of JSON Schemas into a hosted API
endpoint. You describe the function you need; it generates the implementation,
deploys it as a serverless function, and returns a validated URL. Every tool is
a pure function of its input — generated code is scanned before deploy and
refused if it reaches the network or executes code built at runtime.
This package is the MCP bridge: your endpoints become tools Claude can call
directly. It has **no runtime dependencies** — stdio, `fetch`, and about 500
lines.
Get an API key at
[pritas.github.io/actionforge_ui](https://pritas.github.io/actionforge_ui/#start).
The mapping is close to one-to-one, which is why this wrapper is thin: an
ActionForge tool already *is* an MCP tool — a name, a description, a JSON Schema
for input, and one for output. `tools/list` reads `GET /api/tools`;
`tools/call` posts to the tool's proxy URL.
Implemented directly against the 2025-06-18 protocol schema rather than via the
SDK. That keeps the install to a single package with nothing beneath it, and
every branch stays exercisable offline — `npm run smoke` drives the compiled
server over stdio against a closed port, so the handshake, the silence expected
of a notification, and transport-failure handling are all checked without an
account.
## Install
```bash
npx actionforge-mcp
```
Zero runtime dependencies — the whole server is stdio, `fetch`, and about 500
lines. Nothing to install beyond Node 20.12+.
From a checkout of this repo instead:
```bash
npm install
npm run build
node dist/server.js
```
## Configure
```bash
export ACTIONFORGE_URL=https://your-deployment.example.com
export ACTIONFORGE_API_KEY=af_... # from POST /api/signup, or npm run keygen
npx actionforge-mcp
```
Everything published is scoped to that key's account. Point it at a different
key and it publishes a different tenant's tools — the API enforces the scoping,
so the MCP server cannot see past it.
Transport is stdio with newline-delimited JSON. **stdout carries protocol
frames only**; all logging goes to stderr, because anything else corrupts the
stream a client is parsing.
## Claude Desktop
`claude_desktop_config.json`:
```json
{
"mcpServers": {
"actionforge": {
"command": "npx",
"args": ["-y", "actionforge-mcp"],
"env": {
"ACTIONFORGE_URL": "https://your-deployment.example.com",
"ACTIONFORGE_API_KEY": "af_..."
}
}
}
}
```
## Claude Code
```bash
claude mcp add actionforge \
--env ACTIONFORGE_URL=https://your-deployment.example.com \
--env ACTIONFORGE_API_KEY=af_... \
-- npx -y actionforge-mcp
```
## How failures are reported
The protocol draws a line this server follows exactly, because it decides
whether a model can recover on its own:
| Situation | Reported as | Why |
|---|---|---|
| Arguments fail the tool's `input_schema` (400) | result with `isError: true` | The model can read the validation detail and fix the call |
| Tool not ready yet (503) | result with `isError: true` | Transient — retry shortly |
| Rate limited (429) | result with `isError: true` | Includes how long to wait |
| Tool ran but broke its own `output_schema` (502) | result with `isError: true`, named as a fault in the tool | Not the model's arguments |
| Tool does not exist (404), or an unknown tool name | JSON-RPC error | Nothing the model can correct; the client should re-list |
| ActionForge unreachable | JSON-RPC error `-32603` | Transport failure, not a tool result |
Anything the model could act on stays inside the result where it can see it.
Only genuinely exceptional conditions become protocol errors.
## Caching
The tool list is cached for 30 seconds, and the cache is dropped immediately
when a tool turns out to be gone — so a deleted tool disappears on the next
listing rather than lingering until the TTL expires.
## Publishing
```bash
npm run build && npm run smoke
npm publish --access public
```
`dist/` is gitignored — it is a build artifact, rebuilt by `prepublishOnly`, so
what npm receives is always compiled from the committed source.
Bump `version` before each publish; npm refuses to overwrite a released
version.