@venumdev/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Venum
+
+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,157 @@
+# Venum MCP
+
+Composable Solana execution infrastructure, for coding agents.
+
+`@venumdev/mcp` is the MCP server for the Venum Solana execution stack. It gives coding agents and trading agents a stable tool surface for prices, pools, quotes, swap building, local signing + submission, and transaction tracking. It is designed to work with `Venum Skills` for higher-level workflows and agent context.
+
+- Website: [www.venum.dev](https://www.venum.dev)
+- CLI: [github.com/venumhq/solana-venum-cli](https://github.com/venumhq/solana-venum-cli)
+- Skills: [github.com/venumhq/solana-venum-skills](https://github.com/venumhq/solana-venum-skills)
+- Terminal: [github.com/venumhq/solana-venum-terminal](https://github.com/venumhq/solana-venum-terminal)
+
+Venum's core product direction stays the same:
+
+> Less raw RPC. More executable actions.
+
+This repo is the MCP-native part of that OSS surface.
+
+## What It Does
+
+- Exposes Venum execution primitives as MCP tools
+- Wraps the Venum CLI in JSON mode for stable machine-readable tool results
+- Keeps the initial tool surface narrow and composable
+- Fits coding-agent and trading-agent workflows better than raw RPC glue
+
+## Tool Surface
+
+- `health`
+- `price`
+- `prices`
+- `pools`
+- `tokens`
+- `quote`
+- `swap_build`
+- `swap_sign_and_submit`
+- `tx_status`
+
+## Install
+
+Run without installing:
+
+```bash
+pnpm dlx @venumdev/mcp
+```
+
+Install globally:
+
+```bash
+pnpm add -g @venumdev/mcp
+venum-mcp
+```
+
+Install locally:
+
+```bash
+pnpm add @venumdev/mcp
+```
+
+## API Key
+
+Most Venum tools require an API key.
+
+Get one at [www.venum.dev](https://www.venum.dev), then configure the underlying CLI once:
+
+```bash
+venum config set api-key <your-key>
+```
+
+If you already saved your key with `venum config set api-key`, `@venumdev/mcp` will reuse that config automatically through the Venum CLI. In that case, you usually do not need to pass `VENUM_API_KEY` again in the MCP client config.
+
+Or pass environment variables to the MCP process:
+
+```bash
+VENUM_API_KEY=<your-key>
+VENUM_API_URL=https://api.venum.dev
+```
+
+## How It Works
+
+The current implementation is intentionally thin:
+
+- MCP receives a tool call
+- the server invokes `@venumdev/cli`
+- the CLI runs in `--json` mode
+- the MCP server returns the parsed JSON result to the agent
+
+This keeps the tool contract stable while the broader Venum SDK and MCP surface evolves.
+
+## Example MCP Config
+
+If your machine already has a saved Venum CLI config, this is enough:
+
+```json
+{
+  "mcpServers": {
+    "venum": {
+      "command": "pnpm",
+      "args": ["dlx", "@venumdev/mcp"]
+    }
+  }
+}
+```
+
+If you want to pass the API key directly to the MCP process:
+
+```json
+{
+  "mcpServers": {
+    "venum": {
+      "command": "pnpm",
+      "args": ["dlx", "@venumdev/mcp"],
+      "env": {
+        "VENUM_API_KEY": "<your-key>"
+      }
+    }
+  }
+}
+```
+
+This works well for Claude, OpenCode, and other stdio-based MCP clients.
+
+You can also use a global install instead of `pnpm dlx`:
+
+```json
+{
+  "mcpServers": {
+    "venum": {
+      "command": "venum-mcp"
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm start
+pnpm check
+pnpm publint
+```
+
+## Why This Exists
+
+The Venum plan is to build the composable Solana execution layer for coding agents and trading agents.
+
+That means:
+
+- CLI-first workflows
+- JSON-native outputs
+- stable tool semantics
+- fewer moving parts than raw RPC plus custom infra glue
+
+`@venumdev/mcp` is the direct expression of that strategy.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+const require = createRequire(import.meta.url);
+const cliPackagePath = require.resolve('@venumdev/cli/package.json');
+const cliEntry = join(dirname(cliPackagePath), 'dist', 'index.js');
+const tools = [
+    {
+        name: 'health',
+        description: 'Check Venum API health.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        buildArgs: () => ['health'],
+    },
+    {
+        name: 'price',
+        description: 'Get one token price by symbol or mint.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                token: { type: 'string', description: 'Token symbol or mint.' },
+            },
+            required: ['token'],
+            additionalProperties: false,
+        },
+        buildArgs: (args) => ['price', requiredString(args, 'token')],
+    },
+    {
+        name: 'prices',
+        description: 'Get prices for one or more tokens.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tokens: {
+                    oneOf: [
+                        { type: 'string', description: 'Comma-separated tokens.' },
+                        { type: 'array', items: { type: 'string' }, description: 'Array of token symbols or mints.' },
+                    ],
+                },
+            },
+            additionalProperties: false,
+        },
+        buildArgs: (args) => {
+            const tokens = optionalTokenList(args.tokens);
+            return tokens ? ['prices', tokens] : ['prices'];
+        },
+    },
+    {
+        name: 'pools',
+        description: 'List pools filtered by token, pair, or DEX.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                token: { type: 'string' },
+                tokens: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
+                tokenA: { type: 'string' },
+                tokenB: { type: 'string' },
+                dex: { type: 'string' },
+                limit: { type: 'number' },
+                offset: { type: 'number' },
+            },
+            additionalProperties: false,
+        },
+        buildArgs: (args) => {
+            const result = ['pools'];
+            if (typeof args.token === 'string')
+                result.push('--token', args.token);
+            const tokens = optionalTokenList(args.tokens);
+            if (tokens)
+                result.push('--tokens', tokens);
+            if (typeof args.tokenA === 'string' && typeof args.tokenB === 'string')
+                result.push(args.tokenA, args.tokenB);
+            if (typeof args.dex === 'string')
+                result.push('--dex', args.dex);
+            if (typeof args.limit === 'number')
+                result.push('--limit', String(args.limit));
+            if (typeof args.offset === 'number')
+                result.push('--offset', String(args.offset));
+            return result;
+        },
+    },
+    {
+        name: 'tokens',
+        description: 'List supported tokens, optionally filtered by category.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        buildArgs: (args) => {
+            const result = ['tokens'];
+            if (typeof args.category === 'string')
+                result.push('--category', args.category);
+            return result;
+        },
+    },
+    {
+        name: 'quote',
+        description: 'Quote a swap route between two tokens.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                inputMint: { type: 'string' },
+                outputMint: { type: 'string' },
+                amount: { type: 'string' },
+                slippageBps: { type: 'number' },
+            },
+            required: ['inputMint', 'outputMint', 'amount'],
+            additionalProperties: false,
+        },
+        buildArgs: (args) => {
+            const result = ['quote', requiredString(args, 'inputMint'), requiredString(args, 'outputMint'), requiredString(args, 'amount')];
+            if (typeof args.slippageBps === 'number')
+                result.push('--slippage', String(args.slippageBps));
+            return result;
+        },
+    },
+    {
+        name: 'swap_build',
+        description: 'Build an unsigned swap transaction.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                inputMint: { type: 'string' },
+                outputMint: { type: 'string' },
+                amount: { type: 'string' },
+                wallet: { type: 'string', description: 'Wallet public key.' },
+                slippageBps: { type: 'number' },
+            },
+            required: ['inputMint', 'outputMint', 'amount', 'wallet'],
+            additionalProperties: false,
+        },
+        buildArgs: (args) => {
+            const result = [
+                'swap',
+                'build',
+                requiredString(args, 'inputMint'),
+                requiredString(args, 'outputMint'),
+                requiredString(args, 'amount'),
+                '--wallet',
+                requiredString(args, 'wallet'),
+            ];
+            if (typeof args.slippageBps === 'number')
+                result.push('--slippage', String(args.slippageBps));
+            return result;
+        },
+    },
+    {
+        name: 'swap_sign_and_submit',
+        description: 'Sign a Venum swap locally and submit it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                inputMint: { type: 'string' },
+                outputMint: { type: 'string' },
+                amount: { type: 'string' },
+                keypair: { type: 'string', description: 'Path to local Solana keypair JSON.' },
+                slippageBps: { type: 'number' },
+                wait: { type: 'boolean' },
+                buildFile: { type: 'string' },
+                quoteId: { type: 'string' },
+                tx: { type: 'string' },
+                file: { type: 'string' },
+            },
+            required: ['keypair'],
+            additionalProperties: false,
+        },
+        buildArgs: (args) => {
+            const result = ['swap', 'sign-and-submit'];
+            if (typeof args.buildFile === 'string') {
+                result.push('--build-file', args.buildFile);
+            }
+            else if (typeof args.quoteId === 'string') {
+                result.push('--quote-id', args.quoteId);
+                if (typeof args.tx === 'string')
+                    result.push('--tx', args.tx);
+                if (typeof args.file === 'string')
+                    result.push('--file', args.file);
+            }
+            else {
+                result.push(requiredString(args, 'inputMint'), requiredString(args, 'outputMint'), requiredString(args, 'amount'));
+            }
+            result.push('--keypair', requiredString(args, 'keypair'));
+            if (typeof args.slippageBps === 'number')
+                result.push('--slippage', String(args.slippageBps));
+            if (args.wait === true)
+                result.push('--wait');
+            return result;
+        },
+    },
+    {
+        name: 'tx_status',
+        description: 'Check transaction status by signature.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                signature: { type: 'string' },
+            },
+            required: ['signature'],
+            additionalProperties: false,
+        },
+        buildArgs: (args) => ['tx', requiredString(args, 'signature')],
+    },
+];
+const server = new Server({
+    name: '@venumdev/mcp',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = tools.find((candidate) => candidate.name === request.params.name);
+    if (!tool) {
+        return toolError(`Unknown tool: ${request.params.name}`);
+    }
+    try {
+        const args = tool.buildArgs((request.params.arguments ?? {}));
+        const result = await runVenumJson(args);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return toolError(error instanceof Error ? error.message : String(error));
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+async function runVenumJson(args) {
+    const output = await runCommand([...args, '--json']);
+    return JSON.parse(output);
+}
+function runCommand(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [cliEntry, ...args], {
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve(stdout.trim());
+                return;
+            }
+            reject(new Error(stderr.trim() || stdout.trim() || `venum exited with code ${code ?? 'unknown'}`));
+        });
+    });
+}
+function requiredString(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`Missing required string argument: ${key}`);
+    }
+    return value;
+}
+function optionalTokenList(value) {
+    if (typeof value === 'string' && value.trim() !== '')
+        return value;
+    if (Array.isArray(value)) {
+        const tokens = value.filter((item) => typeof item === 'string' && item.trim() !== '');
+        if (tokens.length > 0)
+            return tokens.join(',');
+    }
+    return undefined;
+}
+function toolError(message) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: message,
+            },
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@venumdev/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Venum, the Solana execution layer for coding agents and trading agents. Designed to work with Venum Skills.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "venum-mcp": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "publint": "publint",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm build"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "venum",
+    "solana",
+    "mcp",
+    "skills",
+    "agent",
+    "cli",
+    "trading",
+    "defi"
+  ],
+  "author": "Venum <hello@venum.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venumhq/solana-venum-mcp.git"
+  },
+  "homepage": "https://www.venum.dev",
+  "bugs": {
+    "url": "https://github.com/venumhq/solana-venum-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@venumdev/cli": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "publint": "^0.3.18",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}