mcp-caller 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ab498
+
+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,75 @@
+# mcp-caller
+
+`mcp-caller` is a small MCP client CLI that starts an MCP server, performs the protocol handshake, and calls a tool by JSON input.
+
+## Install
+
+```bash
+cd culled/mcp-caller
+npm install
+```
+
+## Usage
+
+Call a stdio MCP server:
+
+```bash
+node index.js \
+  --server-json '{"type":"stdio","command":"uvx","args":["--from","git+https://github.com/macsymwang/hello-mcp-server.git","hello-mcp-server"]}' \
+  --call-json '{"tool":"say_hello","params":{"name":"world"}}'
+```
+
+Call a remote streamable HTTP MCP server:
+
+```bash
+node index.js \
+  --server-json '{"mcpServers":{"context7":{"type":"streamable-http","url":"https://mcp.context7.com/mcp","headers":{"CONTEXT7_API_KEY":"YOUR_API_KEY"}}}}' \
+  --call-json '{"tool":"resolve-library-id","params":{"query":"Express","libraryName":"Express"}}'
+```
+
+Read JSON from files instead of inline values:
+
+```bash
+node index.js --server-file server.json --call-file call.json
+```
+
+## JSON Shapes
+
+Server JSON:
+
+```json
+{
+  "mcpServers": {
+    "name": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["server.js"]
+    }
+  }
+}
+```
+
+Or a single server object:
+
+```json
+{
+  "type": "streamable-http",
+  "url": "https://example.com/mcp",
+  "headers": {}
+}
+```
+
+Call JSON:
+
+```json
+{
+  "tool": "tool-name",
+  "params": {}
+}
+```
+
+## Notes
+
+- The CLI prints text content when the tool result contains text.
+- Use `--pretty` to format non-text JSON output.
+- The Context7 integration example is covered by [test/cli.examples.test.js](d:/projects/culled/mcp-caller/test/cli.examples.test.js).

package/index.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+function printUsage() {
+  console.error(`Usage:
+  mcp-caller --server-json <json> --call-json <json>
+  mcp-caller --server-file <path> --call-file <path>
+
+Server JSON shape:
+  { "mcpServers": { "name": { ... } } }
+  or a single server object with:
+  { "type": "streamable-http", "url": "...", "headers": { ... } }
+  { "type": "stdio", "command": "...", "args": [...], "cwd": "...", "env": { ... } }
+
+Call JSON shape:
+  { "tool": "tool-name", "params": { ... } }
+`);
+}
+
+function parseJson(raw, label) {
+  try {
+    const trimmed = raw.trim();
+    const candidates = [
+      trimmed,
+      (trimmed.startsWith("'") && trimmed.endsWith("'")) || (trimmed.startsWith('"') && trimmed.endsWith('"'))
+        ? trimmed.slice(1, -1)
+        : trimmed,
+      trimmed.replace(/\\"/g, '"')
+    ];
+
+    let lastError;
+    for (const candidate of candidates) {
+      try {
+        return JSON.parse(candidate);
+      } catch (error) {
+        lastError = error;
+      }
+    }
+
+    throw lastError ?? new Error("Unable to parse JSON");
+  } catch (error) {
+    throw new Error(`Invalid ${label}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function readSource(options, jsonKey, fileKey, label) {
+  if (options[fileKey]) {
+    return parseJson(readFileSync(options[fileKey], "utf8"), label);
+  }
+  if (options[jsonKey]) {
+    return parseJson(options[jsonKey], label);
+  }
+  throw new Error(`Missing ${label}`);
+}
+
+function parseArgs(argv) {
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (token === "--server-json") {
+      options.serverJson = argv[++i];
+      continue;
+    }
+    if (token === "--server-file") {
+      options.serverFile = argv[++i];
+      continue;
+    }
+    if (token === "--call-json") {
+      options.callJson = argv[++i];
+      continue;
+    }
+    if (token === "--call-file") {
+      options.callFile = argv[++i];
+      continue;
+    }
+    if (token === "--server-name") {
+      options.serverName = argv[++i];
+      continue;
+    }
+    if (token === "--pretty") {
+      options.pretty = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${token}`);
+  }
+  return options;
+}
+
+function resolveServerDefinition(serverSource, serverName) {
+  if (serverSource?.mcpServers && typeof serverSource.mcpServers === "object") {
+    const entries = Object.entries(serverSource.mcpServers);
+    if (entries.length === 0) {
+      throw new Error("server JSON contains an empty mcpServers object");
+    }
+    const selectedName = serverName ?? entries[0][0];
+    const selectedServer = serverSource.mcpServers[selectedName];
+    if (!selectedServer) {
+      throw new Error(`Server "${selectedName}" was not found in mcpServers`);
+    }
+    return { name: selectedName, server: selectedServer };
+  }
+
+  return { name: serverName ?? "server", server: serverSource };
+}
+
+function createTransport(server) {
+  if (!server || typeof server !== "object") {
+    throw new Error("Server definition must be an object");
+  }
+
+  if (server.type === "streamable-http") {
+    if (!server.url) {
+      throw new Error("streamable-http server is missing url");
+    }
+    return new StreamableHTTPClientTransport(new URL(server.url), {
+      requestInit: {
+        headers: server.headers ?? {}
+      }
+    });
+  }
+
+  if (server.type === "stdio") {
+    if (!server.command) {
+      throw new Error("stdio server is missing command");
+    }
+    return new StdioClientTransport({
+      command: server.command,
+      args: Array.isArray(server.args) ? server.args : [],
+      cwd: server.cwd,
+      env: server.env ?? {},
+      stderr: "inherit"
+    });
+  }
+
+  throw new Error(`Unsupported server type: ${server.type}`);
+}
+
+function extractText(result) {
+  const pieces = [];
+  for (const item of result?.content ?? []) {
+    if (item?.type === "text" && typeof item.text === "string") {
+      pieces.push(item.text);
+    }
+  }
+  return pieces.join("\n");
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printUsage();
+    return;
+  }
+
+  const serverSource = readSource(options, "serverJson", "serverFile", "--server-json/--server-file");
+  const callSource = readSource(options, "callJson", "callFile", "--call-json/--call-file");
+
+  if (!callSource || typeof callSource !== "object") {
+    throw new Error("Call JSON must be an object");
+  }
+  if (typeof callSource.tool !== "string" || !callSource.tool) {
+    throw new Error('Call JSON must include a non-empty "tool" string');
+  }
+
+  const { server } = resolveServerDefinition(serverSource, options.serverName);
+  const transport = createTransport(server);
+  const client = new Client({ name: "mcp-caller", version: "0.0.1" }, { capabilities: {} });
+
+  try {
+    await client.connect(transport);
+
+    const result = await client.callTool({
+      name: callSource.tool,
+      arguments: callSource.params ?? callSource.arguments ?? {}
+    });
+
+    const text = extractText(result);
+    if (text) {
+      console.log(text);
+      return;
+    }
+
+    console.log(JSON.stringify(result, null, options.pretty ? 2 : 0));
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "mcp-caller",
+  "version": "0.0.1",
+  "description": "A small MCP client CLI that can start a server and call a tool from JSON input.",
+  "type": "module",
+  "main": "index.js",
+  "bin": "./index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:context7": "vitest run test/cli.examples.test.js -t \"Context7 resolve-library-id\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.4"
+  },
+  "keywords": [
+    "mcp",
+    "cli",
+    "stdio",
+    "streamable-http"
+  ],
+  "author": "ab498",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}