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
// @three-ws/agent-sniper — MCP (Model Context Protocol) stdio face.
//
// Exposes the sniper engine as an MCP stdio server so AI agents / Claude can arm
// strategies, snipe pump.fun coins by hand, and inspect open positions — all over
// the same engine handle the CLI and HTTP faces drive. Every tool maps 1:1 onto a
// public engine/store method; no engine internals are reached around.
//
// Run standalone:
// node src/faces/mcp.js
// # network/mode come from SNIPER_NETWORK / SNIPER_MODE when no sniper is injected.
//
// Or wire into Claude Desktop / Cursor by pointing the MCP client at that command.
//
// Testability: `createSniperMcpServer(deps)` builds and returns the fully-registered
// McpServer WITHOUT connecting any transport — safe to construct in a test and call
// server.connect(new InMemoryTransport()) on. The stdio boot in `startStdio()` runs
// only when this file is the process entry point.
//
// x402 note: this base server is intentionally unauthenticated and local. Paid
// gating can be layered by wrapping each tool handler (settle USDC, then delegate) —
// the three.ws *hosted* MCP does exactly that. We do NOT implement payment here; the
// surface stays lightweight so anyone can run it against their own wallet/RPC.
import { createRequire } from 'node:module';
import { pathToFileURL } from 'node:url';
import { realpathSync } from 'node:fs';
import { z } from 'zod';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
// Advertised MCP version tracks package.json so it can't drift from the npm release.
const { version: PKG_VERSION } = createRequire(import.meta.url)('../../package.json');
const SERVER_INSTRUCTIONS =
'agent-sniper over MCP: arm per-agent pump.fun snipe strategies, fire manual buys, and inspect ' +
'positions, all driving a real sniper engine. arm_strategy registers a policy (stop_loss_pct is ' +
'mandatory; SOL amounts are converted to lamports for you). snipe_now forces a manual buy across ' +
'armed agents. list_strategies / list_positions / sniper_status are read-only. close_position and ' +
'disarm_strategy change behavior. This server is unauthenticated and meant to run locally against ' +
'your own wallet/RPC — never expose it on an open port without a payment/auth wrapper.';
// One SOL = 1e9 lamports. SOL inputs are floats; lamports are integers stored as a
// decimal string so a BigInt round-trips through JSON without precision loss.
const LAMPORTS_PER_SOL = 1_000_000_000n;
const solToLamportsString = (sol) => {
// Scale via integer math on a fixed-precision string to avoid float drift on the
// fractional part (e.g. 0.1 SOL must land on exactly 100000000 lamports).
const [whole, frac = ''] = String(sol).split('.');
const fracPadded = (frac + '000000000').slice(0, 9);
const lamports = BigInt(whole || '0') * LAMPORTS_PER_SOL + BigInt(fracPadded || '0');
return lamports.toString();
};
let _idSeq = 0;
const nextStrategyId = () => `strat_${Date.now().toString(36)}_${(++_idSeq).toString(36)}`;
// MCP result envelope helpers. Every handler returns JSON in both a text content
// block (for clients that only read content) and structuredContent (for clients on
// the typed-result path). Errors flip isError but still carry a readable payload.
const ok = (result) => ({
content: [{ type: 'text', text: JSON.stringify(result) }],
structuredContent: result,
});
const fail = (err) => {
const message = err?.message || String(err);
const payload = { ok: false, error: message };
return { content: [{ type: 'text', text: JSON.stringify(payload) }], structuredContent: payload, isError: true };
};
// Write a strategy through whichever method the store exposes. A generic store may
// offer upsertStrategy; the default memory store offers addStrategy (which also
// upserts by id). Either way the stored row is returned to the caller.
function writeStrategy(store, strategy) {
if (typeof store.upsertStrategy === 'function') return store.upsertStrategy(strategy);
if (typeof store.addStrategy === 'function') return store.addStrategy(strategy);
throw new Error('store exposes neither upsertStrategy nor addStrategy — cannot arm a strategy');
}
// Read a single strategy by id from the engine's live strategy cache.
const findStrategy = (sniper, id) => sniper.strategies().find((s) => s.id === id) || null;
/**
* Build a fully-registered agent-sniper McpServer WITHOUT connecting a transport.
*
* @param {object} [deps]
* @param {object} [deps.sniper] an already-built sniper handle (createSniper / presets.*).
* When omitted, a default `presets.local` sniper is built from SNIPER_NETWORK /
* SNIPER_MODE env, and started so tools operate against a live engine.
* @param {import('../types.js').Store} [deps.store] the store backing `deps.sniper`
* (so tools can read/write strategies + positions). Required when `deps.sniper` is
* supplied; auto-derived when this function builds the default sniper.
* @returns {Promise<McpServer>}
*/
export async function createSniperMcpServer(deps = {}) {
let { sniper, store } = deps;
if (!sniper) {
// No injected handle → stand up the zero-config local wiring. Build the store
// first so it's shared with the sniper and reachable by the tools.
const { createMemoryStore } = await import('../adapters/store/memory.js');
store = store || createMemoryStore({});
const { createPumpClient } = await import('../adapters/solana/pump-client.js');
const { createSelfCustodyWallet } = await import('../adapters/wallet/self-custody.js');
const { createWeb3Executor } = await import('../adapters/solana/executor-web3.js');
const { createPumpPortalFeed } = await import('../adapters/feed/pumpportal.js');
const { createSniper } = await import('../engine.js');
const network = (process.env.SNIPER_NETWORK || 'mainnet').trim();
const mode = (process.env.SNIPER_MODE || 'simulate').trim();
const solana = await createPumpClient({ network });
sniper = createSniper({
config: { network, mode },
store,
wallet: createSelfCustodyWallet({}),
solana,
executor: createWeb3Executor(),
feed: createPumpPortalFeed({ network }),
});
await sniper.start();
}
if (!store) {
throw new Error('[agent-sniper/mcp] deps.store is required when deps.sniper is supplied');
}
const server = new McpServer(
{ name: 'agent-sniper', version: PKG_VERSION },
{
// Our tool surface is fixed per-process — declare tools with no
// list_changed notifications so strict 2025-06-18 clients don't wait for them.
capabilities: { tools: { listChanged: false } },
instructions: SERVER_INSTRUCTIONS,
},
);
// ── arm_strategy ──────────────────────────────────────────────────────────────
// Registers / updates an armed strategy. Not read-only (it changes future trading
// behavior) but not destructive (it creates state, deletes nothing). SOL ceilings
// are converted to lamport strings to match the Strategy contract.
server.registerTool(
'arm_strategy',
{
title: 'Arm snipe strategy',
description:
'Register (or update) a pump.fun snipe strategy for an agent. SOL amounts are converted to ' +
'lamports for you. stop_loss_pct is mandatory — the engine refuses to arm without it. Returns ' +
'the stored strategy row.',
inputSchema: {
agentId: z.string().min(1).describe('Owning agent id — one wallet per agent.'),
strategyId: z.string().min(1).optional().describe('Reuse to update an existing strategy; omit to create one.'),
per_trade_sol: z.number().positive().describe('SOL committed per snipe.'),
daily_budget_sol: z.number().positive().describe('SOL/day spend ceiling for this agent.'),
stop_loss_pct: z.number().describe('REQUIRED. Exit when down this percent from entry.'),
take_profit_pct: z.number().optional().describe('Exit when up this percent from entry.'),
trailing_stop_pct: z.number().optional().describe('Exit when down this percent from peak.'),
max_hold_seconds: z.number().int().positive().optional().describe('Hard time-stop (default 1800).'),
slippage_bps: z.number().int().nonnegative().optional().describe('Entry slippage tolerance, bps (default 500).'),
max_price_impact_pct: z.number().optional().describe('Entry circuit breaker (default 10).'),
trigger: z.enum(['new_mint', 'intel_confirmed', 'first_claim', 'manual']).optional().describe('What fires the buy.'),
network: z.enum(['mainnet', 'devnet']).optional().describe('Chain (defaults to the sniper network).'),
mev_tip_mode: z.enum(['off', 'economy', 'turbo']).optional().describe('MEV tip aggressiveness.'),
firewall_level: z.enum(['block', 'warn', 'off']).optional().describe('Rug/honeypot firewall posture.'),
min_market_cap_usd: z.number().optional().describe('Skip candidates below this market cap.'),
max_market_cap_usd: z.number().optional().describe('Skip candidates above this market cap.'),
require_socials: z.boolean().optional().describe('Require twitter/telegram/website on the candidate.'),
},
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
},
async (input) => {
try {
const id = input.strategyId || nextStrategyId();
const strategy = {
id,
agent_id: input.agentId,
enabled: true,
trigger: input.trigger || 'new_mint',
network: input.network || sniper.config.network,
per_trade_lamports: solToLamportsString(input.per_trade_sol),
daily_budget_lamports: solToLamportsString(input.daily_budget_sol),
stop_loss_pct: input.stop_loss_pct,
};
// Only set optional fields when supplied — keep the row clean for stores
// that round-trip it to a typed column (null vs absent matters in SQL).
if (input.take_profit_pct != null) strategy.take_profit_pct = input.take_profit_pct;
if (input.trailing_stop_pct != null) strategy.trailing_stop_pct = input.trailing_stop_pct;
if (input.max_hold_seconds != null) strategy.max_hold_seconds = input.max_hold_seconds;
if (input.slippage_bps != null) strategy.slippage_bps = input.slippage_bps;
if (input.max_price_impact_pct != null) strategy.max_price_impact_pct = input.max_price_impact_pct;
if (input.mev_tip_mode != null) strategy.mev_tip_mode = input.mev_tip_mode;
if (input.firewall_level != null) strategy.firewall_level = input.firewall_level;
if (input.min_market_cap_usd != null) strategy.min_market_cap_usd = input.min_market_cap_usd;
if (input.max_market_cap_usd != null) strategy.max_market_cap_usd = input.max_market_cap_usd;
if (input.require_socials != null) strategy.require_socials = input.require_socials;
const stored = (await writeStrategy(store, strategy)) || strategy;
return ok({ ok: true, strategy: stored });
} catch (err) {
return fail(err);
}
},
);
// ── disarm_strategy ─────────────────────────────────────────────────────────────
// Flips a strategy off. Patches enabled=false (re-arm later by id) rather than
// deleting, so the policy isn't lost. Falls back to removeStrategy if the store
// can't patch. Marked destructive: it stops future buys for the agent.
server.registerTool(
'disarm_strategy',
{
title: 'Disarm snipe strategy',
description: 'Disable an armed strategy (enabled=false). The agent stops sniping new candidates; open positions still exit on their own rules.',
inputSchema: { strategyId: z.string().min(1).describe('Strategy id to disarm.') },
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
},
async ({ strategyId }) => {
try {
const cur = findStrategy(sniper, strategyId);
if (cur) {
await writeStrategy(store, { ...cur, enabled: false });
} else if (typeof store.removeStrategy === 'function') {
store.removeStrategy(strategyId);
} else {
return fail(new Error(`strategy "${strategyId}" not found`));
}
return ok({ ok: true, strategyId, enabled: false });
} catch (err) {
return fail(err);
}
},
);
// ── list_strategies ─────────────────────────────────────────────────────────────
server.registerTool(
'list_strategies',
{
title: 'List armed strategies',
description: 'List every currently armed strategy the sniper is evaluating candidates against.',
inputSchema: {},
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
},
async () => {
try {
const strategies = sniper.strategies();
return ok({ ok: true, count: strategies.length, strategies });
} catch (err) {
return fail(err);
}
},
);
// ── snipe_now ───────────────────────────────────────────────────────────────────
// Force a manual buy of a specific mint. force:true bypasses the feed scorer and
// runs every armed strategy's buy directly. Not read-only — it spends.
server.registerTool(
'snipe_now',
{
title: 'Snipe a mint now',
description: 'Force a manual buy of a pump.fun mint across all armed agents (bypasses the candidate scorer). In simulate mode no funds move.',
inputSchema: {
mint: z.string().min(1).describe('The pump.fun token mint to buy.'),
symbol: z.string().optional().describe('Optional ticker for logs/screen.'),
agentId: z.string().optional().describe('Reserved for future per-agent targeting; current build snipes all armed agents.'),
},
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
},
async ({ mint, symbol, agentId }) => {
try {
const candidate = { mint, entry_trigger: 'manual' };
if (symbol) candidate.symbol = symbol;
sniper.submitCandidate(candidate, { force: true });
return ok({ ok: true, scheduled: true, mint, agentId: agentId || null });
} catch (err) {
return fail(err);
}
},
);
// ── list_positions ──────────────────────────────────────────────────────────────
server.registerTool(
'list_positions',
{
title: 'List positions',
description: 'List sniper positions, optionally filtered by agentId and/or status (opening|open|closing|closed|failed).',
inputSchema: {
agentId: z.string().optional().describe('Filter to one agent.'),
status: z.enum(['opening', 'open', 'closing', 'closed', 'failed']).optional().describe('Filter by lifecycle status.'),
},
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
},
async ({ agentId, status }) => {
try {
if (typeof store.listPositions !== 'function') {
throw new Error('store does not expose listPositions — cannot enumerate positions');
}
const positions = await store.listPositions({ agentId, network: sniper.config.network, status });
return ok({ ok: true, count: positions.length, positions });
} catch (err) {
return fail(err);
}
},
);
// ── close_position ──────────────────────────────────────────────────────────────
// The engine handle deliberately does not expose executeSell, so rather than
// reaching into the executor we flip the position's kill_switch via the store. The
// next position sweep (cfg.pollMs) sees kill_switch and exits the position through
// the normal sell path — same code, no duplicated broadcast logic. Hence the result
// is { scheduled: true }: the close is queued for the upcoming sweep, not synchronous.
server.registerTool(
'close_position',
{
title: 'Close a position',
description: 'Schedule an exit for an open position. Flips its kill switch; the next position sweep sells it through the normal exit path. Returns once scheduled — the sell lands shortly after.',
inputSchema: { positionId: z.string().min(1).describe('Position id to close (from list_positions).') },
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
},
async ({ positionId }) => {
try {
if (typeof store.listPositions !== 'function' || typeof store.updatePosition !== 'function') {
throw new Error('store must expose listPositions + updatePosition to close a position');
}
const all = await store.listPositions({ network: sniper.config.network });
const pos = all.find((p) => p.id === positionId);
if (!pos) return fail(new Error(`position "${positionId}" not found on ${sniper.config.network}`));
if (pos.status === 'closed' || pos.status === 'failed') {
return ok({ ok: true, scheduled: false, positionId, status: pos.status, note: 'position already terminal' });
}
await store.updatePosition(positionId, { kill_switch: true });
return ok({ ok: true, scheduled: true, positionId });
} catch (err) {
return fail(err);
}
},
);
// ── sniper_status ───────────────────────────────────────────────────────────────
server.registerTool(
'sniper_status',
{
title: 'Sniper status',
description: 'Engine health snapshot: event/candidate/buy/sell counts, armed-strategy count, queue depth, plus the network and mode.',
inputSchema: {},
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
},
async () => {
try {
const result = {
ok: true,
network: sniper.config.network,
mode: sniper.config.mode,
stats: sniper.stats(),
};
return ok(result);
} catch (err) {
return fail(err);
}
},
);
return server;
}
/**
* Build the server and connect it over stdio. stdout is reserved for MCP JSON-RPC
* frames, so all human logging goes to stderr.
*
* @param {object} [deps] same shape as createSniperMcpServer.
* @returns {Promise<McpServer>}
*/
export async function startStdio(deps = {}) {
const server = await createSniperMcpServer(deps);
const transport = new StdioServerTransport();
await server.connect(transport);
console.error(`[agent-sniper/mcp] ready — sniper tools registered over stdio (v${PKG_VERSION})`);
return server;
}
// Run the stdio boot ONLY when this file is the process entry point. Importing the
// module (tests, the CLI `mcp` subcommand reusing createSniperMcpServer) must NOT
// connect a transport. argv[1] is compared both directly and via realpath so a launch
// through an npm-bin symlink still resolves to this module.
function isProcessEntryPoint() {
const argvPath = process.argv[1];
if (!argvPath) return false;
if (import.meta.url === pathToFileURL(argvPath).href) return true;
try {
return import.meta.url === pathToFileURL(realpathSync(argvPath)).href;
} catch {
return false;
}
}
if (isProcessEntryPoint()) {
startStdio().catch((err) => {
console.error(`agent-sniper/mcp: ${err?.message || err}`);
process.exit(1);
});
}
export default { createSniperMcpServer, startStdio };