TypeScript SDK for Gopher Orch - AI Agent orchestration framework with native performance
npm install gopher-orchTypeScript SDK for Gopher Orch - AI Agent orchestration framework with native C++ performance.
- Features
- When to Use This SDK
- Architecture
- Installation
- Quick Start
- Building from Source
- Prerequisites
- Step 1: Clone the Repository
- Step 2: Build Everything
- Step 3: Verify the Build
- Step 4: Run Tests
- Native Library Details
- Library Location
- Platform-Specific Library Names
- Custom Library Path
- Library Search Order
- API Documentation
- GopherAgent
- ServerConfig
- Error Handling
- Examples
- Basic Usage with API Key
- Using Local MCP Servers
- Running the Example
- Development
- Project Structure
- Build Scripts
- Rebuilding Native Library
- Updating Submodules
- Troubleshooting
- Contributing
- License
---
- Native Performance - Powered by C++ core with TypeScript bindings via koffi
- AI Agent Framework - Build intelligent agents with LLM integration
- MCP Protocol - Model Context Protocol client and server support
- Tool Orchestration - Manage and execute tools across multiple MCP servers
- State Management - Built-in state graph for complex workflows
- Type Safety - Full TypeScript typing with strict mode support
This SDK is ideal for:
- Node.js applications that need high-performance AI agent orchestration
- Backend services requiring MCP protocol support
- CLI tools needing reliable agent infrastructure
- Server-side applications integrating AI agents
``
┌─────────────────────────────────────────────────────────────┐
│ Your Application │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ TypeScript SDK (gopher-orch) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ GopherAgent │ │ ServerConfig│ │ Error Classes │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ FFI (koffi)
▼
┌─────────────────────────────────────────────────────────────┐
│ Native Library (libgopher-orch) │
│ ┌───────────────┐ ┌───────────────┐ ┌─────────────────┐ │
│ │ Agent Engine │ │ LLM Providers │ │ MCP Client │ │
│ │ │ │ - Anthropic │ │ - HTTP/SSE │ │
│ │ │ │ - OpenAI │ │ - Tool Registry │ │
│ └───────────────┘ └───────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP Servers │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Weather API │ │ Database │ │ Custom Tools │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
`bash`
npm install gopher-orch
See Building from Source below.
`typescript
import { GopherAgent, GopherAgentConfig } from 'gopher-orch';
// Create an agent
const agent = GopherAgent.create(
GopherAgentConfig.builder()
.provider('AnthropicProvider')
.model('claude-3-haiku-20240307')
.apiKey(process.env.ANTHROPIC_API_KEY!)
.build()
);
try {
// Run a query
const answer = agent.run('What is the weather like in Tokyo?');
console.log(answer);
} finally {
// Clean up
agent.dispose();
}
`
- Node.js 18+ - JavaScript runtime
- CMake 3.14+ - Build system generator
- C++ Compiler - GCC 9+, Clang 10+, or MSVC 2019+
- Git - Version control
`bash`
git clone --recursive https://github.com/GopherSecurity/gopher-mcp-js.git
cd gopher-mcp-js
The build.sh script handles everything: submodule updates, native library compilation, npm install, and TypeScript build:
`bash`
./build.sh
`bashCheck native libraries
ls -la native/lib/
$3
bash
npm test
`Native Library Details
$3
After building, native libraries are installed to:
native/
├── lib/
│ ├── libgopher-orch.dylib # Main library
│ ├── libgopher-mcp.dylib # MCP protocol library
│ └── libfmt.dylib # Formatting library
└── include/
└── orch/ # Header files
$3
| Platform | Library Name |
|----------|--------------|
| macOS |
|
| Linux | libgopher-orch.so |
| Windows | gopher-orch.dll |$3
Set the
GOPHER_ORCH_LIBRARY_PATH environment variable to specify a custom location:`bash
export GOPHER_ORCH_LIBRARY_PATH=/custom/path/libgopher-orch.dylib
`$3
1.
environment variable
2. native/lib/ in current directory
3. native/lib/ relative to module location
4. System paths (/usr/local/lib, /opt/homebrew/lib, /usr/lib)API Documentation
$3
The main class for interacting with the agent:
`typescript
// Static methods
GopherAgent.init(): void // Initialize library
GopherAgent.shutdown(): void // Shutdown library
GopherAgent.isInitialized(): boolean // Check if initialized
GopherAgent.create(config): GopherAgent // Create agent with config
GopherAgent.createWithApiKey(...): GopherAgent
GopherAgent.createWithServerConfig(...): GopherAgent// Instance methods
agent.run(query, timeoutMs?): string // Run a query
agent.runDetailed(query, timeoutMs?): AgentResult // Run with metadata
agent.dispose(): void // Free resources
agent.isDisposed(): boolean // Check if disposed
`$3
Utility for fetching server configurations:
typescript
const config = ServerConfig.fetch(apiKey);
`$3
The SDK provides typed exceptions:
typescript
try {
const agent = GopherAgent.create(config);
const result = agent.run('query');
} 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);
}
}
`Examples
$3
typescript
import { GopherAgent, GopherAgentConfig } from 'gopher-orch';const agent = GopherAgent.createWithApiKey(
'AnthropicProvider',
'claude-3-haiku-20240307',
process.env.ANTHROPIC_API_KEY!
);
try {
const answer = agent.run('Hello, how are you?');
console.log(answer);
} finally {
agent.dispose();
}
`$3
typescript
import { GopherAgent, GopherAgentConfig } from 'gopher-orch';const serverConfig = JSON.stringify({
servers: [
{
name: 'weather',
transport: 'HTTP_SSE',
url: 'http://localhost:3001/mcp'
}
]
});
const agent = GopherAgent.createWithServerConfig(
'AnthropicProvider',
'claude-3-haiku-20240307',
serverConfig
);
try {
const answer = agent.run('What is the weather in Tokyo?');
console.log(answer);
} finally {
agent.dispose();
}
`$3
bash
Start local MCP servers
cd examples/server3001 && npm install && npm start &
cd examples/server3002 && npm install && npm start &Run the example
npm run example
`Development
$3
gopher-mcp-js/
├── src/ # TypeScript source
│ ├── index.ts # Main exports
│ ├── agent.ts # GopherAgent class
│ ├── config.ts # Configuration builder
│ ├── result.ts # AgentResult class
│ ├── errors.ts # Error classes
│ ├── serverConfig.ts # ServerConfig utility
│ └── ffi/ # FFI bindings
│ ├── index.ts
│ └── library.ts # koffi bindings
├── tests/ # Jest tests
├── examples/ # Example applications
├── third_party/ # Git submodules
│ └── gopher-orch/ # Native library source
├── native/ # Built native libraries (after build)
├── dist/ # Compiled TypeScript (after build)
├── package.json
├── tsconfig.json
├── jest.config.js
└── build.sh # Build script
$3
bash
./build.sh # Build everything
./build.sh --clean # Clean and rebuild
npm run build # TypeScript only
npm test # Run tests
npm run example # Run example
npm run lint # Run ESLint
npm run lint:fix # Run ESLint with auto-fix
npm run format # Format code with Prettier
npm run format:check # Check formatting
`$3
bash
./build.sh --clean --build
`$3
bash
git submodule update --init --recursive
`For custom SSH hosts (multiple GitHub accounts):
bash
GITHUB_SSH_HOST=your-ssh-alias ./build.sh
`Troubleshooting
$3
If you get "Failed to load gopher-orch native library", check:
1. Native library exists:
2. Environment variable:
3. Rebuild: $3
bash
git submodule deinit -f third_party/gopher-orch
rm -rf .git/modules/third_party/gopher-orch
git submodule update --init --recursive
`$3
On macOS, you may need to allow the library in System Preferences > Security & Privacy.
Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests:
MIT License - See LICENSE for details.