Gopher Mcp Js

TypeScript SDK for AI Agent orchestration with MCP (Model Context Protocol) support.

npm version License: Apache 2.0

Features

• Multi-Provider LLM Support - Anthropic, OpenAI, Google, Azure, and more
• MCP Protocol - Full Model Context Protocol client support
• Native Performance - Powered by C++ core with TypeScript bindings
• Tool Orchestration - Execute tools across multiple MCP servers
• Type Safety - Full TypeScript support with strict mode

Supported LLM Providers

Provider	Models
Anthropic	Claude 3.5 Sonnet, Claude 3 Haiku, Claude 3 Opus
OpenAI	GPT-4o, GPT-4o-mini, GPT-4 Turbo
Google	Gemini 2.5 Flash, Gemini 2.0 Pro
Azure OpenAI	GPT-4o, GPT-4 (via Azure deployment)

Installation

npm install @gopher.security/gopher-mcp-js

The package automatically installs the correct native library for your platform:

• macOS (ARM64, x64)
• Linux (ARM64, x64)
• Windows (ARM64, x64)

Quick Start

Using Gopher API Key (Recommended)

import { GopherAgent } from '@gopher.security/gopher-mcp-js';

// Create agent with Gopher API key (fetches MCP config automatically)
const agent = GopherAgent.createWithApiKey(
  'AnthropicProvider',
  'claude-3-haiku-20240307',
  process.env.GOPHER_API_KEY!
);

try {
  const answer = agent.run('List all my Gmail drafts');
  console.log(answer);
} finally {
  agent.dispose();
}

Using Custom Server Configuration

import { GopherAgent } from '@gopher.security/gopher-mcp-js';

const serverConfig = JSON.stringify({
  succeeded: true,
  code: 200000000,
  message: 'success',
  data: {
    servers: [
      {
        version: '2025-01-09',
        serverId: '1',
        name: 'my-server',
        transport: 'http_sse',
        config: { url: 'http://localhost:3001/mcp', headers: {} },
        connectTimeout: 5000,
        requestTimeout: 30000,
      },
    ],
  },
});

const agent = GopherAgent.createWithServerConfig(
  'OpenAIProvider',
  'gpt-4o-mini',
  serverConfig
);

try {
  const answer = agent.run('What tools are available?');
  console.log(answer);
} finally {
  agent.dispose();
}

Using Configuration Builder

import { GopherAgent, GopherAgentConfig } from '@gopher.security/gopher-mcp-js';

const config = GopherAgentConfig.builder()
  .provider('AnthropicProvider')
  .model('claude-3-haiku-20240307')
  .apiKey(process.env.GOPHER_API_KEY!)
  .build();

const agent = GopherAgent.create(config);

try {
  const answer = agent.run('Hello, what can you do?');
  console.log(answer);
} finally {
  agent.dispose();
}

API Reference

GopherAgent

// Create agent with Gopher API key
GopherAgent.createWithApiKey(provider, model, apiKey): GopherAgent

// Create agent with server configuration JSON
GopherAgent.createWithServerConfig(provider, model, serverConfigJson): GopherAgent

// Create agent with config object
GopherAgent.create(config): GopherAgent

// Run a query
agent.run(query, timeoutMs?): string

// Run with detailed result
agent.runDetailed(query, timeoutMs?): AgentResult

// Release resources (must be called when done)
agent.dispose(): void

Error Handling

import {
  GopherAgent,
  AgentError,
  ApiKeyError,
  ConnectionError,
  TimeoutError
} from '@gopher.security/gopher-mcp-js';

try {
  const agent = GopherAgent.createWithApiKey(provider, model, apiKey);
  const result = agent.run('query');
  agent.dispose();
} catch (e) {
  if (e instanceof ApiKeyError) {
    console.error('Invalid API key:', e.message);
  } else if (e instanceof ConnectionError) {
    console.error('Connection failed:', e.message);
  } else if (e instanceof TimeoutError) {
    console.error('Operation timed out:', e.message);
  } else if (e instanceof AgentError) {
    console.error('Agent error:', e.message);
  }
}

Environment Variables

Variable	Description
GOPHER_API_KEY	Your Gopher API key (get one at https://gopher.security)
ANTHROPIC_API_KEY	Required when using AnthropicProvider
OPENAI_API_KEY	Required when using OpenAIProvider
GOOGLE_API_KEY	Required when using GoogleProvider
AZURE_OPENAI_API_KEY	Required when using AzureProvider
GOPHER_DEBUG=1	Enable debug logging

Platform Packages

The SDK uses platform-specific packages for native binaries:

Platform	Package
macOS ARM64	@gopher.security/gopher-orch-darwin-arm64
macOS x64	@gopher.security/gopher-orch-darwin-x64
Linux ARM64	@gopher.security/gopher-orch-linux-arm64
Linux x64	@gopher.security/gopher-orch-linux-x64
Windows ARM64	@gopher.security/gopher-orch-win32-arm64
Windows x64	@gopher.security/gopher-orch-win32-x64

These are installed automatically as optional dependencies.

Requirements

• Node.js 18+
• Supported platforms: macOS, Linux, Windows (ARM64 or x64)

Troubleshooting

Native library not found

If you see "Failed to load gopher-mcp native library":

1. Ensure you're on a supported platform
2. Try reinstalling: npm install @gopher.security/gopher-mcp-js --force
3. Enable debug logging: GOPHER_DEBUG=1 node your-app.js

Permission errors on macOS

xattr -d com.apple.quarantine node_modules/@gopher.security/gopher-orch-darwin-*/lib/*.dylib

Links

• GitHub Repository
• Gopher Security
• MCP Protocol Specification

License

Apache License 2.0 - See LICENSE for details.