agentforge-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sciscale studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# agentforge-mcp
+
+**Stop re-explaining what you want.** An MCP server that turns a rough,
+one-line coding request into a structured, tool-tuned prompt — so your AI
+coding agent gets it right the first time.
+
+It's a thin client for [AgentForge](https://agentforge.sciscale.org): it
+forwards your request to the hosted engine, which extracts the real
+requirements, catches the edge cases you didn't mention, formats the prompt
+for your specific agent, and quality-checks it before handing it back.
+
+No engine logic runs locally — this package is a ~150-line forwarder. The work
+happens server-side, so it stays current without you updating anything.
+
+## Setup
+
+### 1. Get an API key
+
+Sign in at [agentforge.sciscale.org](https://agentforge.sciscale.org), open
+**API keys**, and create one. Free accounts get 3 refinements/day; Pro is
+unlimited. The key is shown once — copy it.
+
+### 2. Add the server to your coding agent
+
+The server runs via `npx` — nothing to install or build.
+
+**Claude Code:**
+
+```sh
+claude mcp add agentforge --env AGENTFORGE_API_KEY=af_your_key_here -- npx -y agentforge-mcp
+```
+
+**Cursor / Windsurf / Claude Desktop** — add to your MCP config
+(`~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "agentforge": {
+      "command": "npx",
+      "args": ["-y", "agentforge-mcp"],
+      "env": { "AGENTFORGE_API_KEY": "af_your_key_here" }
+    }
+  }
+}
+```
+
+## The tool
+
+### `agentforge_refine_prompt`
+
+Turns a plain-language request into a refined prompt.
+
+| Argument | Type | Default | Notes |
+|---|---|---|---|
+| `request` | string | — | The coding task, in plain language (1–4000 chars). Rough is fine. |
+| `target_tool` | string | `claude-code` | `claude-code`, `codex`, `cursor`, `aider`, `continue`, `windsurf`, `kimi`, `generic` |
+| `style` | string | `plan-first` | `plan-first`, `direct-edit`, `explore-first` |
+
+Returns the refined prompt as text. The structured result also includes the
+account `tier`, the Quality Engine `quality` score, and today's `usage`.
+
+Once configured, just ask your agent — e.g. *"refine this with AgentForge: add
+a dark mode toggle that persists, then implement it."*
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `AGENTFORGE_API_KEY` | — | **Required.** Your API key. |
+| `AGENTFORGE_API_URL` | `https://agentforge.sciscale.org/api/v1/refine` | Override the endpoint (rarely needed). |
+
+## Develop
+
+```sh
+npm install
+npm run build      # tsc -> dist/
+node dist/index.js # runs on stdio
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE). A project of [sciscale studio](https://wow.sciscale.org).

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * agentforge-mcp — MCP server for AgentForge.
+ *
+ * A thin stdio MCP server exposing one tool, `agentforge_refine_prompt`, which
+ * forwards a plain-language coding request to the AgentForge HTTP API
+ * (POST /api/v1/refine) and returns a tool-tuned, quality-checked prompt.
+ *
+ * No engine logic lives here — AgentForge's backend does the work. This is a
+ * pure forwarder. Get an API key at https://agentforge.sciscale.org/account/keys
+ * and pass it via the AGENTFORGE_API_KEY environment variable.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * agentforge-mcp — MCP server for AgentForge.
+ *
+ * A thin stdio MCP server exposing one tool, `agentforge_refine_prompt`, which
+ * forwards a plain-language coding request to the AgentForge HTTP API
+ * (POST /api/v1/refine) and returns a tool-tuned, quality-checked prompt.
+ *
+ * No engine logic lives here — AgentForge's backend does the work. This is a
+ * pure forwarder. Get an API key at https://agentforge.sciscale.org/account/keys
+ * and pass it via the AGENTFORGE_API_KEY environment variable.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_URL = process.env.AGENTFORGE_API_URL ?? "https://agentforge.sciscale.org/api/v1/refine";
+const API_KEY = process.env.AGENTFORGE_API_KEY ?? "";
+// Pro-tier iterative refinement can run several audit passes — allow for it.
+const REQUEST_TIMEOUT_MS = 180_000;
+// Mirror the values the AgentForge backend accepts (app/prompt_builder.py).
+const TARGET_TOOLS = [
+    "claude-code", "codex", "cursor", "aider",
+    "continue", "windsurf", "kimi", "generic",
+];
+const STYLES = ["plan-first", "direct-edit", "explore-first"];
+const inputSchema = {
+    request: z.string()
+        .min(1, "request must not be empty")
+        .max(4000, "request must not exceed 4000 characters")
+        .describe("The coding task or feature request, in plain language. Rough and " +
+        "under-specified is fine — that is exactly what gets refined."),
+    target_tool: z.enum(TARGET_TOOLS)
+        .default("claude-code")
+        .describe("The AI coding agent the prompt is formatted for."),
+    style: z.enum(STYLES)
+        .default("plan-first")
+        .describe("Execution style baked into the prompt: 'plan-first' plans before " +
+        "coding, 'direct-edit' makes the smallest change, 'explore-first' " +
+        "maps the codebase first."),
+};
+const outputSchema = {
+    prompt: z.string()
+        .describe("The refined, tool-tuned prompt — hand this to your coding agent."),
+    tier: z.string().describe("Account tier that produced it: 'free' or 'pro'."),
+    quality: z.object({
+        score: z.number(),
+        max_score: z.number(),
+        passed: z.boolean(),
+    }).nullable().describe("Quality Engine score, or null if scoring was unavailable."),
+    usage: z.object({
+        used_today: z.number(),
+        limit: z.number().nullable(),
+    }).describe("Today's usage for this account; 'limit' is null for unlimited Pro."),
+};
+const server = new McpServer({ name: "agentforge-mcp", version: "0.1.0" });
+server.registerTool("agentforge_refine_prompt", {
+    title: "Refine a prompt with AgentForge",
+    description: `Turn a rough, plain-language coding request into a structured, tool-tuned prompt for an AI coding agent.
+
+AgentForge extracts the real requirements, fills in missing edge cases, formats the prompt for the target agent's conventions, and runs it through a Quality Engine before returning it. Reach for this when a request is vague or under-specified and you want a sharper prompt before handing it to a coding agent.
+
+Args:
+  - request (string, required): the coding task in plain language, 1-4000 chars.
+  - target_tool (string): one of claude-code, codex, cursor, aider, continue, windsurf, kimi, generic. Default: claude-code.
+  - style (string): plan-first, direct-edit, or explore-first. Default: plan-first.
+
+Returns the refined prompt as text. structuredContent additionally carries:
+  {
+    "prompt": string,
+    "tier": "free" | "pro",
+    "quality": { "score": number, "max_score": number, "passed": boolean } | null,
+    "usage": { "used_today": number, "limit": number | null }
+  }
+
+Errors are returned as text, e.g.:
+  - "API key not configured" — set AGENTFORGE_API_KEY.
+  - "invalid or revoked API key" (401) — check the key at agentforge.sciscale.org.
+  - "daily free limit reached" (429) — upgrade to Pro for unlimited calls.`,
+    inputSchema,
+    outputSchema,
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+}, async ({ request, target_tool, style }) => {
+    if (!API_KEY) {
+        return toolError("API key not configured. Set the AGENTFORGE_API_KEY environment " +
+            "variable — create a key at https://agentforge.sciscale.org/account/keys");
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    let resp;
+    try {
+        resp = await fetch(API_URL, {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${API_KEY}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ input: request, target_tool, style }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        return toolError(err instanceof Error && err.name === "AbortError"
+            ? `AgentForge did not respond within ${REQUEST_TIMEOUT_MS / 1000}s — try again.`
+            : `could not reach AgentForge: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!resp.ok) {
+        return toolError(await describeHttpError(resp));
+    }
+    const data = (await resp.json());
+    const structured = {
+        prompt: data.prompt,
+        tier: data.tier,
+        quality: data.quality,
+        usage: data.usage,
+    };
+    return {
+        content: [{ type: "text", text: data.prompt }],
+        structuredContent: structured,
+    };
+});
+function toolError(message) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${message}` }],
+    };
+}
+async function describeHttpError(resp) {
+    let detail = "";
+    try {
+        const body = (await resp.json());
+        if (body.detail)
+            detail = ` — ${body.detail}`;
+    }
+    catch {
+        /* error body was not JSON; the status code alone will have to do */
+    }
+    switch (resp.status) {
+        case 401:
+            return "invalid or revoked API key. Check AGENTFORGE_API_KEY, or create " +
+                "a new key at https://agentforge.sciscale.org/account/keys";
+        case 429:
+            return `daily free limit reached${detail}. Upgrade to Pro for unlimited ` +
+                "calls at https://agentforge.sciscale.org/pricing";
+        case 400:
+        case 422:
+            return `the request was rejected${detail}.`;
+        default:
+            return `AgentForge API returned HTTP ${resp.status}${detail}.`;
+    }
+}
+async function main() {
+    if (!API_KEY) {
+        // Don't exit — start anyway so the client can connect and the tool call
+        // returns a clear, actionable message instead of a generic launch failure.
+        console.error("agentforge-mcp: warning — AGENTFORGE_API_KEY is not set; refine calls " +
+            "will fail until it is.");
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the protocol channel — all logging must go to stderr.
+    console.error("agentforge-mcp running (stdio)");
+}
+main().catch((err) => {
+    console.error("agentforge-mcp fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "agentforge-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for AgentForge — turn rough requests into tool-tuned, quality-checked prompts for AI coding agents.",
+  "license": "MIT",
+  "author": "sciscale studio",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agentforge-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agentforge",
+    "prompt-engineering",
+    "claude-code",
+    "cursor",
+    "ai-coding-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Liyue2341/agentforge-mcp.git"
+  },
+  "homepage": "https://agentforge.sciscale.org",
+  "bugs": {
+    "url": "https://github.com/Liyue2341/agentforge-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  }
+}