@civic/nexus-client

TypeScript client library for connecting to Civic Nexus Hub and exposing MCP (Model Context Protocol) tools to AI SDKs like Vercel AI, OpenAI, and Anthropic.

Installation

pnpm add @civic/nexus-client

Depending on which AI SDK you're using, also install the peer dependency:

# For Vercel AI SDK
pnpm add ai

# For OpenAI
pnpm add openai

# For Anthropic
pnpm add @anthropic-ai/sdk

Quick Start

With Vercel AI SDK

import { NexusClient } from "@civic/nexus-client";
import { vercelAIAdapter } from "@civic/nexus-client/adapters/vercel-ai";
import { streamText } from "ai";

const nexus = new NexusClient({
  auth: {
    token: "your-access-token",
  },
});

const tools = await nexus.getTools(vercelAIAdapter());

const result = streamText({
  model: yourModel,
  messages: [{ role: "user", content: "Search GitHub for civic repos" }],
  tools,
});

// Clean up when done
await nexus.close();

With OpenAI SDK

import { NexusClient } from "@civic/nexus-client";
import { openAIAdapter } from "@civic/nexus-client/adapters/openai";
import OpenAI from "openai";

const nexus = new NexusClient({
  auth: { token: "your-access-token" },
});

const tools = await nexus.getTools(openAIAdapter());

const openai = new OpenAI();
const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Search GitHub for civic repos" }],
  tools,
});

With Anthropic SDK

import { NexusClient } from "@civic/nexus-client";
import { anthropicAdapter } from "@civic/nexus-client/adapters/anthropic";
import Anthropic from "@anthropic-ai/sdk";

const nexus = new NexusClient({
  auth: { token: "your-access-token" },
});

const tools = await nexus.getTools(anthropicAdapter());

const anthropic = new Anthropic();
const message = await anthropic.messages.create({
  model: "claude-3-5-sonnet-20241022",
  messages: [{ role: "user", content: "Search GitHub for civic repos" }],
  tools,
});

Features

• Session Management: Maintains persistent MCP sessions with automatic reconnection
• Framework Agnostic: Works with any AI SDK through adapters
• TypeScript First: Full type safety and IntelliSense support
• Flexible Authentication: Support for static tokens or async token providers
• Lightweight: No unnecessary dependencies, minimal bundle size

API Reference

NexusClient

Constructor Options

interface NexusClientConfig {
  // Hub URL (defaults to "https://nexus.civic.com/hub/mcp")
  url?: string;

  // Authentication
  auth: {
    token: string | (() => Promise<string>);
  };

  // Optional custom headers
  headers?: Record<string, string>;

  // Optional connection options
  reconnection?: {
    maxRetries?: number;
    initialDelay?: number;
    maxDelay?: number;
    delayGrowFactor?: number;
  };
}

Methods

• getTools<T>(adapter?: ToolAdapter<T>): Promise<T> - Get tools, optionally adapted for specific AI SDK
• getServerInstructions(): Promise<string> - Get server instructions for system prompt
• callTool(name: string, args: unknown): Promise<CallToolResult> - Call a tool directly
• close(): Promise<void> - Close the connection

Advanced Usage

Caching Client Instances

The library doesn't include caching logic - you manage NexusClient instances yourself:

// Simple in-memory cache
const clientCache = new Map<string, NexusClient>();

function getNexusClient(userId: string): NexusClient {
  let client = clientCache.get(userId);
  if (!client) {
    client = new NexusClient({ /* config */ });
    clientCache.set(userId, client);
  }
  return client;
}

Custom Headers (Profile/Account Context)

const nexus = new NexusClient({
  auth: { token: accessToken },
  headers: {
    "x-civic-profile": "personal",
    "x-civic-account-id": "account-123",
  },
});

Dynamic Token Refresh

const nexus = new NexusClient({
  auth: {
    token: async () => {
      const session = await getSession();
      return session.accessToken;
    },
  },
});

License

MIT