Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// AST analysis behind the MCP annotation-safety gate.
//
// Separated from scripts/audit-mcp-safety.mjs so the rules can be exercised
// against fixture sources in tests/mcp-safety-audit.test.js: a gate nobody has
// watched fail is a gate nobody knows works.
//
// See the CLI for why this check exists and what each rule means.
import { readFileSync, existsSync } from 'node:fs';
import { dirname, join, relative, resolve as resolvePath } from 'node:path';
import { parse } from 'acorn';
import { ROOT } from './mcp-tool-sources.mjs';
// ---------------------------------------------------------------------------
// Mutation vocabulary
// ---------------------------------------------------------------------------
// Helper calls that sign, send, or settle. Matched on the callee's final
// identifier, so `conn.sendTransaction(...)` and `sendTransaction(...)` both hit.
export const MUTATION_CALLS = new Map([
['sendTransaction', 'tx-send'],
['sendRawTransaction', 'tx-send'],
['sendAndConfirmTransaction', 'tx-send'],
['sendVersionedTransaction', 'tx-send'],
['signTransaction', 'tx-sign'],
['partialSign', 'tx-sign'],
['hedgedSend', 'tx-send'],
['settlePayment', 'payment-settle'],
['transferUsdc', 'funds-transfer'],
['transferSol', 'funds-transfer'],
['solanaTransfer', 'funds-transfer'],
['mintTo', 'mint'],
['createMint', 'mint'],
['mintAsset', 'mint'],
]);
// Evidence classes that make an action irreversible, so `destructiveHint: false`
// is wrong for them.
export const IRREVERSIBLE = new Set(['tx-send', 'tx-sign', 'payment-settle', 'funds-transfer', 'mint']);
// A `sql` tagged template whose text opens with one of these is a write.
const SQL_WRITE = /^\s*(?:--[^\n]*\n|\s)*(insert|update|delete|truncate|drop|alter)\b/i;
// ---------------------------------------------------------------------------
// AST helpers
// ---------------------------------------------------------------------------
const FUNCTION_TYPES = new Set([
'FunctionDeclaration',
'FunctionExpression',
'ArrowFunctionExpression',
]);
/** Walk every child node, depth-first. */
function walk(node, visit) {
if (!node || typeof node.type !== 'string') return;
visit(node);
for (const key of Object.keys(node)) {
if (key === 'type' || key === 'start' || key === 'end') continue;
const value = node[key];
if (Array.isArray(value)) {
for (const child of value) walk(child, visit);
} else if (value && typeof value.type === 'string') {
walk(value, visit);
}
}
}
/**
* A string-literal or template-literal property value, with `${…}` standing in
* for interpolations so a description stays readable and stable.
*/
function stringValue(node, constStrings = new Map(), seen = new Set()) {
if (!node) return null;
if (node.type === 'Literal' && typeof node.value === 'string') return node.value;
if (node.type === 'TemplateLiteral') {
return node.quasis.map((q) => q.value.cooked ?? '').join('${…}');
}
// Long descriptions are routinely written as `'part one ' + 'part two'`.
if (node.type === 'BinaryExpression' && node.operator === '+') {
const left = stringValue(node.left, constStrings, seen);
const right = stringValue(node.right, constStrings, seen);
if (left !== null && right !== null) return left + right;
}
// `description: DESCRIPTION`, where the text is a module-level constant.
if (node.type === 'Identifier' && constStrings.has(node.name) && !seen.has(node.name)) {
return stringValue(constStrings.get(node.name), constStrings, new Set([...seen, node.name]));
}
// `… + ALLOWED_HOSTS.join(', ') + …`: a literal list rendered into the copy.
if (
node.type === 'CallExpression' &&
node.callee.type === 'MemberExpression' &&
node.callee.property?.name === 'join' &&
node.callee.object?.type === 'Identifier' &&
constStrings.has(node.callee.object.name)
) {
const array = constStrings.get(node.callee.object.name);
if (array?.type === 'ArrayExpression') {
const parts = array.elements.map((el) => stringValue(el, constStrings, seen));
if (parts.every((part) => part !== null)) {
const sep = stringValue(node.arguments[0], constStrings, seen) ?? ',';
return parts.join(sep);
}
}
}
return null;
}
const STRINGY_NODES = ['Literal', 'TemplateLiteral', 'BinaryExpression', 'Identifier'];
/**
* Every const in a module whose value could resolve to a string, plus the same
* from each module it imports a name out of. One hop is enough: descriptions
* reference shared constants (`… + THREE_MINT + …`), they do not chain.
*/
function collectConstStrings(ast, relPath, depth = 1) {
const out = new Map();
walk(ast, (node) => {
if (node.type !== 'VariableDeclarator' || node.id?.type !== 'Identifier') return;
if (node.init && (STRINGY_NODES.includes(node.init.type) || node.init.type === 'ArrayExpression')) {
out.set(node.id.name, node.init);
}
});
if (depth <= 0) return out;
for (const [local, binding] of collectImports(ast, relPath)) {
if (out.has(local)) continue;
const dep = loadModule(binding.path);
if (!dep) continue;
const value = dep.constStrings.get(binding.imported);
if (value) out.set(local, value);
}
return out;
}
/**
* The value a property holds, including `get description() { return '…' }`,
* which a few tools use to compose a description from other constants.
*/
function propertyValue(prop) {
if (!prop) return null;
if (prop.kind !== 'get') return prop.value;
const body = prop.value?.body?.body ?? [];
const returned = body.find((s) => s.type === 'ReturnStatement');
return returned?.argument ?? null;
}
/** The final identifier of a callee: `a.b.c()` -> "c", `c()` -> "c". */
function calleeName(callee) {
if (!callee) return null;
if (callee.type === 'Identifier') return callee.name;
if (callee.type === 'MemberExpression' && !callee.computed) {
return callee.property?.name ?? null;
}
return null;
}
/**
* Local name -> resolved absolute path, for every relative import in a module.
* Extension-less specifiers are not used in this repo's ESM sources, so a
* specifier is resolved as written.
*/
function collectImports(ast, relPath) {
const dir = dirname(join(ROOT, relPath));
const bindings = new Map();
for (const node of ast.body) {
if (node.type !== 'ImportDeclaration') continue;
const source = node.source.value;
if (typeof source !== 'string' || !source.startsWith('.')) continue;
const target = resolvePath(dir, source);
if (!existsSync(target)) continue;
for (const spec of node.specifiers) {
if (spec.type === 'ImportSpecifier') {
bindings.set(spec.local.name, { path: target, imported: spec.imported.name });
}
}
}
return bindings;
}
/** Map of every function declared at any level of a module, by name. */
function collectNamedFunctions(ast) {
const fns = new Map();
walk(ast, (node) => {
if (node.type === 'FunctionDeclaration' && node.id?.name) {
fns.set(node.id.name, node);
} else if (node.type === 'VariableDeclarator' && node.id?.type === 'Identifier') {
if (node.init && FUNCTION_TYPES.has(node.init.type)) fns.set(node.id.name, node.init);
} else if (
node.type === 'Property' &&
!node.computed &&
node.key?.name &&
node.value &&
FUNCTION_TYPES.has(node.value.type)
) {
// Object-literal methods, incl. `async handler(...)` shorthand.
if (!fns.has(node.key.name)) fns.set(node.key.name, node.value);
}
});
return fns;
}
/**
* Unwrap the object-literal inside `Object.freeze({...})`, which is how several
* servers declare their shared annotation constants.
*/
function unwrapObject(node) {
if (!node) return null;
if (node.type === 'ObjectExpression') return node;
if (
node.type === 'CallExpression' &&
calleeName(node.callee) === 'freeze' &&
node.arguments.length === 1
) {
return unwrapObject(node.arguments[0]);
}
return null;
}
/**
* Boolean-valued properties of an object literal, resolving `...SPREAD` of a
* local constant so shared annotation constants compose the way they do at
* runtime (`{ title: '…', ...LIVE_READ }`).
*/
function objectBooleans(objNode, constObjects, seen = new Set()) {
const values = {};
const target = unwrapObject(objNode);
if (!target || seen.has(target)) return values;
seen.add(target);
for (const prop of target.properties) {
if (prop.type === 'SpreadElement') {
const source =
prop.argument.type === 'Identifier'
? constObjects.get(prop.argument.name)
: unwrapObject(prop.argument);
if (source) Object.assign(values, objectBooleans(source, constObjects, seen));
continue;
}
if (prop.type !== 'Property' || prop.computed) continue;
const key = prop.key?.name ?? prop.key?.value;
if (prop.value?.type === 'Literal' && typeof prop.value.value === 'boolean') {
values[key] = prop.value.value;
}
}
return values;
}
/** Resolve an `annotations` property to plain booleans, following a local const. */
function readAnnotations(node, constObjects) {
if (!node) return { kind: 'missing', values: {} };
let target = node;
if (node.type === 'Identifier') {
target = constObjects.get(node.name);
if (!target) return { kind: 'unresolved', values: {}, ref: node.name };
}
if (!unwrapObject(target)) return { kind: 'dynamic', values: {} };
return { kind: 'resolved', values: objectBooleans(target, constObjects) };
}
/** Every object literal assigned to a const, by name (Object.freeze unwrapped). */
function collectConstObjects(ast) {
const out = new Map();
walk(ast, (node) => {
if (node.type !== 'VariableDeclarator' || node.id?.type !== 'Identifier') return;
const obj = unwrapObject(node.init);
if (obj) out.set(node.id.name, obj);
});
return out;
}
const HINT_KEYS = new Set([
'readOnlyHint',
'destructiveHint',
'idempotentHint',
'openWorldHint',
]);
/**
* Annotations declared in a name-keyed overlay map rather than inline on the
* tool def. The pump.fun server declares its tool list and its annotations as
* two separate exports (`TOOLS` + `TOOL_ANNOTATIONS`) and merges them at
* registration, so an inline-only reader would see 25 unannotated tools.
* @returns {Map<string, Record<string, boolean>>} tool name -> hints
*/
function collectAnnotationOverlays(constObjects) {
const overlays = new Map();
for (const objNode of constObjects.values()) {
for (const prop of objNode.properties) {
if (prop.type !== 'Property' || prop.computed) continue;
const toolName = prop.key?.name ?? prop.key?.value;
if (typeof toolName !== 'string') continue;
if (!unwrapObject(prop.value)) continue;
const values = objectBooleans(prop.value, constObjects);
if (Object.keys(values).some((key) => HINT_KEYS.has(key))) overlays.set(toolName, values);
}
}
return overlays;
}
/** Parsed module cache: absolute path -> { namedFunctions, imports } or null. */
const moduleCache = new Map();
function loadModule(absPath) {
if (moduleCache.has(absPath)) return moduleCache.get(absPath);
let parsed = null;
try {
const ast = parse(readFileSync(absPath, 'utf8'), {
ecmaVersion: 'latest',
sourceType: 'module',
});
const rel = relative(ROOT, absPath);
parsed = {
namedFunctions: collectNamedFunctions(ast),
imports: collectImports(ast, rel),
constStrings: collectConstStrings(ast, rel, 0),
};
} catch {
parsed = null; // unparseable dependency: nothing to inspect
}
moduleCache.set(absPath, parsed);
return parsed;
}
/**
* Mutation evidence for one handler: every function it actually calls, following
* same-module calls to any depth and calls into an imported function for
* `maxHops` module crossings.
*
* Following a CALL into an imported function is evidence; merely importing a
* module that could mutate is not. That distinction matters: a dozen read-only
* tools import the same Solana RPC helper, and treating the import as evidence
* flagged every one of them.
*
* @returns {Set<string>} evidence labels
*/
function evidenceFor(fnNode, namedFunctions, imports, maxHops = 1) {
const evidence = new Set();
const seen = new Set();
const visitFunction = (fn, scope, hops) => {
if (!fn || seen.has(fn)) return;
seen.add(fn);
const nextSameModule = [];
const nextImported = [];
walk(fn, (node) => {
if (node.type === 'TaggedTemplateExpression') {
const tag = calleeName(node.tag);
const text = node.quasi?.quasis?.[0]?.value?.cooked ?? '';
if (tag === 'sql' && SQL_WRITE.test(text)) evidence.add('db-write');
}
if (node.type !== 'CallExpression') return;
const name = calleeName(node.callee);
if (!name) return;
const label = MUTATION_CALLS.get(name);
if (label) evidence.add(label);
const local = scope.namedFunctions.get(name);
if (local && local !== fn) {
nextSameModule.push(local);
return;
}
const binding = scope.imports.get(name);
if (binding && hops < maxHops) nextImported.push(binding);
});
for (const next of nextSameModule) visitFunction(next, scope, hops);
for (const binding of nextImported) {
const dep = loadModule(binding.path);
if (!dep) continue;
const target = dep.namedFunctions.get(binding.imported);
if (target) visitFunction(target, dep, hops + 1);
}
};
visitFunction(fnNode, { namedFunctions, imports }, 0);
return evidence;
}
/** Extract every tool definition with a handler from one file. */
export function extractTools(relPath) {
const src = readFileSync(join(ROOT, relPath), 'utf8');
let ast;
try {
ast = parse(src, { ecmaVersion: 'latest', sourceType: 'module' });
} catch (error) {
return { parseError: error.message, tools: [] };
}
const namedFunctions = collectNamedFunctions(ast);
const imports = collectImports(ast, relPath);
const constObjects = collectConstObjects(ast);
const overlays = collectAnnotationOverlays(constObjects);
const constStrings = collectConstStrings(ast, relPath);
const tools = [];
walk(ast, (node) => {
if (node.type !== 'ObjectExpression') return;
const props = new Map();
// Getters (`get description() { return … }`) keep their Property node so
// the returned expression can be read; everything else maps to its value.
const propNodes = new Map();
for (const prop of node.properties) {
if (prop.type === 'Property' && !prop.computed) {
const key = prop.key?.name ?? prop.key?.value;
props.set(key, prop.value);
propNodes.set(key, prop);
}
}
const nameNode = props.get('name');
const name =
nameNode?.type === 'Literal' && typeof nameNode.value === 'string' ? nameNode.value : null;
if (!name) return;
// A tool definition, as this repo writes them: a wire name plus a
// description and either a schema or annotations.
if (!props.has('description') || !(props.has('inputSchema') || props.has('annotations'))) return;
const handlerNode = props.get('handler');
const annotations = props.has('annotations')
? readAnnotations(props.get('annotations'), constObjects)
: overlays.has(name)
? { kind: 'resolved', values: overlays.get(name), via: 'overlay' }
: { kind: 'missing', values: {} };
const evidence =
handlerNode && FUNCTION_TYPES.has(handlerNode.type)
? evidenceFor(handlerNode, namedFunctions, imports)
: new Set();
tools.push({
name,
title: stringValue(propertyValue(propNodes.get('title')), constStrings),
description: stringValue(propertyValue(propNodes.get('description')), constStrings),
annotations,
evidence: [...evidence].sort(),
hasHandler: Boolean(handlerNode && FUNCTION_TYPES.has(handlerNode.type)),
});
});
return { tools };
}
// ---------------------------------------------------------------------------
// Rules
// ---------------------------------------------------------------------------
/**
* Violations for one extracted tool.
* @param {{name: string, annotations: object, evidence: string[]}} tool
* @param {string} where label prefixed to each message
* @param {Map<string, string>} exemptions `tool:evidence` -> reason
* @returns {{violations: string[], exempted: string[]}}
*/
export function checkTool(tool, where, exemptions) {
const { name, annotations, evidence } = tool;
const violations = [];
const exempted = [];
if (annotations.kind === 'missing') {
violations.push(
`${where}: no annotations. destructiveHint defaults to TRUE when omitted, so this tool is advertised as destructive. Declare them explicitly.`,
);
return { violations, exempted };
}
if (annotations.kind === 'unresolved') {
violations.push(
`${where}: annotations reference "${annotations.ref}", which is not a local object literal. Declare the constant in this file so the gate can read it.`,
);
return { violations, exempted };
}
if (annotations.kind === 'dynamic') {
violations.push(`${where}: annotations are computed at runtime and cannot be verified.`);
return { violations, exempted };
}
const { readOnlyHint, destructiveHint } = annotations.values;
const unexempted = [];
for (const label of evidence) {
if (exemptions.has(`${name}:${label}`)) exempted.push(`${name} (${label})`);
else unexempted.push(label);
}
if (readOnlyHint === true && unexempted.length) {
violations.push(
`${where}: declares readOnlyHint:true but its handler shows ${unexempted.join(', ')}. An MCP client may auto-approve this call. Set readOnlyHint:false, or add a reviewed EXEMPTIONS entry if the write is a cache/telemetry fill.`,
);
}
const irreversible = unexempted.filter((label) => IRREVERSIBLE.has(label));
if (irreversible.length && destructiveHint === false) {
violations.push(
`${where}: declares destructiveHint:false but its handler shows ${irreversible.join(', ')}, which cannot be undone. Set destructiveHint:true.`,
);
}
return { violations, exempted };
}