[Feature] MCP Server & Agent-Native .void Workflow

[phurpa-tsering]

Use Case

Right now nothing exposes the request runner to an AI agent as a callable tool. An agent that wants to run a request has to shell out to the command-line tool and parse its text output - there's no direct interface for it.

The AI Skill only teaches authoring: it explains how to write a valid request block but says nothing about running one or checking whether it actually worked.

Agent-written .void files are only picked up by accident - the app's general file-watcher treats an agent's write exactly like any other file change, with no verification step and no feedback loop built around it.

Results never get written back into the file itself. Running a file already produces a detailed, structured result (pass/fail, timing, response data) and can save that to a separate output file, but it never goes back into the .void file that produced it.

The core gap: an agent can generate something that looks like a valid .void file, but has no way to check whether it's actually correct or see what a real response looked like.

Proposed Solution

1. An MCP server over the runner - exposes what running requests already does today as tools an agent can call directly, instead of shelling out to a CLI and scraping text:

• Read the project: list which .void files exist and what requests are in them.
• • Execute a request: run a specific request (or a whole file) and get a structured result back - the same execution that happens today, just returned as data instead of console text.
• • • Write the result back into the file: new - today a result only goes to a separate output file; this writes it back into the .void file it came from, so the file carries a record of what actually happened when it last ran.
      This server is just an ordinary local program that stays alive and responds to calls instead of running once and exiting. It has nothing to do with the Voiden desktop app being open - it's a separate process the AI tool starts on the user's machine at the start of a session (pointed at a project folder via a config line), used for the duration of the session, and shut down afterward. Nothing runs remotely and nothing keeps running after the session ends.

2. A bidirectional AI Skill - extend it to teach the full loop, not just authoring:

• Write a request (already covered today).
• • Execute it and read back what actually happened, using the MCP server above.
• • • Fix it if the result shows it's wrong.
      3. First-class treatment of agent-written files - when a .void file appears or changes from outside the app, actively check it's well-formed and surface problems, the same immediate feedback a person gets while typing in the editor, instead of silently accepting whatever lands on disk.

Together: the skill teaches an agent how to write a file, the MCP server lets it execute and get a real result back, and the file-write support confirms what actually landed on disk is valid - the difference between an agent that can generate a plausible file and one that can generate, run, verify, and fix one.

Alternatives Considered

Continuing to rely on the app's general file-watcher and having agents shell out to the CLI and parse text output - this is fragile: nothing catches a mistake until someone opens the file, and there's no structured interface for an agent to use.

Examples

// Conceptual MCP tools exposed over the runner
read_project() -> { files: [...], requests: [...] }
execute_request(file, requestName) -> { pass, timing, response }
write_result(file, requestName, result) -> writes result back into the .void file

Additional Context

Executing a request means making a real HTTP/GraphQL/etc. call - potentially against real APIs with real credentials (auth tokens, API keys from the project's environment variables). Letting an agent trigger that automatically is more sensitive than letting it generate text, and should be thought through deliberately (e.g. requiring explicit confirmation before execution, or scoping which environments an agent is allowed to run against) rather than assumed safe by default.

[aljen-magat-0817]

/**

• MCP runner - minimal safe example
• Node 18+ (global fetch). Usage example:
• PROJECT_DIR=/path/to/project TOKEN=secret node server.js
• Endpoints:
• • GET /read_project -> { files: [ "path/to/file.void", ... ] }
• • POST /execute_request -> { result } (body: { file, requestName, confirm })
• • POST /write_result -> writes back result into file (body: { file, requestName, result })
• Safety defaults:
• • Requires Authorization: Bearer
• • execute_request requires confirm=true to actually perform HTTP requests; otherwise returns a dry-run
• • write_result performs atomic write and marks file with an MCP origin block the watcher can detect
• • Sensitive headers and body keys are redacted before being persisted
    */

import fs from "fs/promises";
import path from "path";
import http from "http";
import crypto from "crypto";
import { pipeline } from "stream/promises";
import zlib from "zlib";

const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
const PORT = Number(process.env.PORT || 0) || 0; // 0 -> random ephemeral port
const TOKEN = process.env.TOKEN || "local-dev-token";
const RESULTS_DIR = path.join(PROJECT_DIR, ".void-results");
const MCP_ORIGIN_MARKER = "// MCP-RESULT-BEGIN"; // watcher can look for this marker
const MAX_INLINE_BODY_BYTES = 2 * 1024; // if >2KB, write sidecar

async function ensureResultsDir() {
await fs.mkdir(RESULTS_DIR, { recursive: true });
}

function jsonResponse(res, code, obj) {
const body = JSON.stringify(obj, null, 2);
res.writeHead(code, {
"Content-Type": "application/json",
"Content-Length": Buffer.byteLength(body),
});
res.end(body);
}

function unauthorized(res) {
jsonResponse(res, 401, { error: "unauthorized" });
}

function requireAuth(req, res) {
const h = req.headers.authorization || "";
if (h !== Bearer ${TOKEN}) {
unauthorized(res);
return false;
}
return true;
}

async function listVoidFiles(dir) {
const out = [];
async function walk(d) {
const entries = await fs.readdir(d, { withFileTypes: true });
await Promise.all(
entries.map(async (ent) => {
const p = path.join(d, ent.name);
if (ent.isDirectory()) {
// skip node_modules and .git to speed up
if (ent.name === "node_modules" || ent.name === ".git" || ent.name === ".void-results") return;
await walk(p);
} else if (ent.isFile() && ent.name.endsWith(".void")) {
out.push(path.relative(PROJECT_DIR, p));
}
})
);
}
await walk(dir);
return out;
}

function redactHeaders(headers) {
const redacted = {};
for (const [k, v] of Object.entries(headers || {})) {
const lk = k.toLowerCase();
if (lk === "authorization" || lk === "cookie" || /set-cookie/i.test(k)) {
redacted[k] = "[REDACTED]";
} else {
redacted[k] = v;
}
}
return redacted;
}

function redactBody(body) {
// If it's JSON, attempt to redact token-like keys
if (!body) return body;
try {
const j = typeof body === "string" ? JSON.parse(body) : body;
function walk(obj) {
if (obj && typeof obj === "object") {
for (const k of Object.keys(obj)) {
if (/token|api[-]?key|secret|password/i.test(k)) {
obj[k] = "[REDACTED]";
} else {
walk(obj[k]);
}
}
}
}
walk(j);
return j;
} catch () {
// not JSON — leave string but don't attempt to store raw credentials
if (typeof body === "string" && body.length > 0 && /token|api[_-]?key|secret|password/i.test(body)) {
return "[REDACTED]";
}
return body;
}
}

async function writeSidecar(basename, requestName, data) {
await ensureResultsDir();
const safeReq = requestName.replace(/[^a-zA-Z0-9._-]/g, "_");
const filename = ${basename}__${safeReq}__${Date.now()}.json.gz;
const outPath = path.join(RESULTS_DIR, filename);
const gz = zlib.createGzip();
const input = Buffer.from(JSON.stringify(data, null, 2), "utf8");
await pipeline(
// Readable from Buffer
async function* () { yield input; }(),
gz,
fs.open(outPath, "w").then(f => f.createWriteStream())
);
return path.relative(PROJECT_DIR, outPath);
}

async function atomicWriteFile(targetPath, content) {
// simple lockfile to avoid concurrent writers
const lockPath = ${targetPath}.lock;
const tmpPath = ${targetPath}.tmp.${crypto.randomBytes(6).toString("hex")};
// try to create lockfile (fail if exists)
try {
const lockHandle = await fs.open(lockPath, "wx");
try {
await fs.writeFile(tmpPath, content, { encoding: "utf8" });
await fs.rename(tmpPath, targetPath); // atomic on same filesystem
} finally {
await lockHandle.close();
await fs.unlink(lockPath).catch(() => {});
await fs.unlink(tmpPath).catch(() => {});
}
} catch (err) {
// if lock exists or other error, bubble up
throw err;
}
}

// Simple parser: find a request block with a name like: // request:
// and capture the block until an empty line or another request marker
function findRequestBlock(fileText, requestName) {
const lines = fileText.split(/\r?\n/);
const beginMarker = request: ${requestName};
let inBlock = false;
const block = [];
for (const ln of lines) {
if (!inBlock && ln.trim().toLowerCase().startsWith(beginMarker)) {
inBlock = true;
continue;
}
if (inBlock) {
// stop if we hit blank line plus not indentation or a next request:
if (ln.trim() === "" || ln.trim().toLowerCase().startsWith("request: ")) break;
block.push(ln);
}
}
return block.join("\n");
}

async function handleReadProject(req, res) {
try {
const files = await listVoidFiles(PROJECT_DIR);
jsonResponse(res, 200, { files });
} catch (err) {
jsonResponse(res, 500, { error: String(err) });
}
}

async function handleExecuteRequest(req, res, body) {
// body: { file, requestName, confirm: boolean }
const { file, requestName, confirm } = body || {};
if (!file || !requestName) return jsonResponse(res, 400, { error: "missing file or requestName" });

const abs = path.join(PROJECT_DIR, file);
let text;
try {
text = await fs.readFile(abs, "utf8");
} catch (err) {
return jsonResponse(res, 404, { error: "file not found", detail: String(err) });
}

const requestBlock = findRequestBlock(text, requestName);
if (!requestBlock) {
return jsonResponse(res, 404, { error: "request not found in file" });
}

// naive parse: look for a first line "METHOD URL"
const firstLine = requestBlock.split(/\r?\n/)[0] || "";
const m = firstLine.trim().match(/^([A-Z]+)\s+(.+)$/);
if (!m) {
return jsonResponse(res, 400, { error: "could not parse request block (expected 'METHOD URL' on first line)" });
}
const method = m[1];
let url = m[2].trim();

// Allow env substitution from process.env with ${VAR}
url = url.replace(/${([A-Z0-9_]+)}/g, (_, n) => process.env[n] || "");

// If not confirmed, return a dry-run preview and extracted metadata without performing network IO
if (!confirm) {
return jsonResponse(res, 200, {
dryRun: true,
method,
url,
note: "set confirm=true to actually perform the HTTP request (requires explicit consent)",
});
}

// perform the fetch (careful: this will send real credentials if present in env or file)
try {
const fetchOpts = { method };
// for the example, we don't parse headers/body from the block; a real impl would
const resp = await fetch(url, fetchOpts);
const headers = Object.fromEntries(resp.headers.entries());
let rawBody;
const buf = await resp.arrayBuffer();
const bodyBytes = Buffer.from(buf);
const isLarge = bodyBytes.length > MAX_INLINE_BODY_BYTES;
if (isLarge) {
rawBody = [stored in sidecar due to size ${bodyBytes.length} bytes];
} else {
// try to decode as utf-8 string
rawBody = bodyBytes.toString("utf8");
}

const result = {
  pass: resp.ok,
  status: resp.status,
  timing_ms: 0, // timing omitted in this minimal example
  headers: redactHeaders(headers),
  body: redactBody(rawBody),
  _raw_bytes: isLarge ? undefined : bodyBytes.length,
};

// if large, write sidecar
if (isLarge) {
  const basename = path.basename(file, ".void");
  const sidecarRel = await writeSidecar(basename, requestName, {
    status: resp.status,
    headers: redactHeaders(headers),
    body: bodyBytes.toString("base64"), // compressed sidecar is gzipped
    meta: { created_at: new Date().toISOString() },
  });
  result.sidecar = sidecarRel;
}

return jsonResponse(res, 200, { result });

} catch (err) {
return jsonResponse(res, 500, { error: "request failed", detail: String(err) });
}
}

function composeResultBlock(requestName, result) {
// Compose a block that can be appended to the .void file. The watcher should look
// for MCP_ORIGIN_MARKER and ignore edits that contain it.
const meta = {
origin: "mcp-server",
version: 1,
timestamp: new Date().toISOString(),
};
// Keep the block human-readable and comment-prefixed so it doesn't break the file parser.
const block = [
MCP_ORIGIN_MARKER,
// request: ${requestName},
// ${JSON.stringify(meta)},
// result: ${JSON.stringify(result).replace(/\n/g, " ")},
"// MCP-RESULT-END",
"",
].join("\n");
return block;
}

async function handleWriteResult(req, res, body) {
// body: { file, requestName, result }
const { file, requestName, result } = body || {};
if (!file || !requestName || !result) return jsonResponse(res, 400, { error: "missing file, requestName or result" });

const abs = path.join(PROJECT_DIR, file);
let text;
try {
text = await fs.readFile(abs, "utf8");
} catch (err) {
return jsonResponse(res, 404, { error: "file not found", detail: String(err) });
}

// redact result again as a defensive measure
const safeResult = {
...result,
headers: redactHeaders(result.headers || {}),
body: redactBody(result.body),
};

// If there's a sidecar specified, ensure we don't inline huge bodies:
if (safeResult.sidecar && typeof safeResult.sidecar === "string") {
safeResult.body = [see sidecar: ${safeResult.sidecar}];
}

const resultBlock = composeResultBlock(requestName, safeResult);

// Append result block to the file and do an atomic write
const newText = ${text.trimEnd()}\n\n${resultBlock};
try {
await atomicWriteFile(abs, newText);
return jsonResponse(res, 200, { ok: true, note: "result written with MCP origin marker" });
} catch (err) {
return jsonResponse(res, 500, { error: "write failed", detail: String(err) });
}
}

async function readRequestBody(req) {
const bufs = [];
for await (const chunk of req) bufs.push(chunk);
if (bufs.length === 0) return null;
try {
return JSON.parse(Buffer.concat(bufs).toString("utf8"));
} catch {
return null;
}
}

async function main() {
await ensureResultsDir();

const server = http.createServer(async (req, res) => {
// simple routing
try {
if (!requireAuth(req, res)) return;
const url = new URL(req.url || "/", http://${req.headers.host || "localhost"});
if (req.method === "GET" && url.pathname === "/read_project") {
return handleReadProject(req, res);
}
if (req.method === "POST" && url.pathname === "/execute_request") {
const body = await readRequestBody(req);
return handleExecuteRequest(req, res, body);
}
if (req.method === "POST" && url.pathname === "/write_result") {
const body = await readRequestBody(req);
return handleWriteResult(req, res, body);
}
jsonResponse(res, 404, { error: "not found" });
} catch (err) {
jsonResponse(res, 500, { error: String(err) });
}
});

server.listen(PORT, "127.0.0.1", () => {
const addr = server.address();
const port = typeof addr === "string" ? addr : addr?.port;
console.log(MCP server listening on http://127.0.0.1:${port});
console.log(TOKEN (bearer): ${TOKEN});
console.log(PROJECT_DIR: ${PROJECT_DIR});
});
}

main().catch((err) => {
console.error("Fatal:", err);
process.exit(1);
});