# Mcp Agent Kit

> The easiest way to create MCP servers, AI agents, and chatbots with any LLM

- **Type:** MCP server
- **Install:** `agentstack add mcp-dominiquekossi-mcp-agent-kit`
- **Verified:** Pending review
- **Seller:** [dominiquekossi](https://agentstack.voostack.com/s/dominiquekossi)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dominiquekossi](https://github.com/dominiquekossi)
- **Source:** https://github.com/dominiquekossi/mcp-agent-kit

## Install

```sh
agentstack add mcp-dominiquekossi-mcp-agent-kit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-agent-kit

> The easiest way to create MCP servers, AI agents, and chatbots with any LLM

[](https://www.npmjs.com/package/mcp-agent-kit)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)

**mcp-agent-kit** is a TypeScript package that simplifies the creation of:

- 🔌 **MCP Servers** (Model Context Protocol)
- 🤖 **AI Agents** with multiple LLM providers
- 🧠 **Intelligent Routers** for multi-LLM orchestration
- 💬 **Chatbots** with conversation memory
- 🌐 **API Helpers** with retry and timeout

## Features

- **Zero Config**: Works out of the box with smart defaults
- **Multi-Provider**: OpenAI, Anthropic, Gemini, Ollama support
- **Type-Safe**: Full TypeScript support with autocomplete
- **Production Ready**: Built-in retry, timeout, and error handling
- **Developer Friendly**: One-line setup for complex features
- **Extensible**: Easy to add custom providers and middleware

## Installation

```bash
npm install mcp-agent-kit
```

## Quick Start

### Create an AI Agent (1 line!)

```typescript
import { createAgent } from "mcp-agent-kit";

const agent = createAgent({ provider: "openai" });
const response = await agent.chat("Hello!");
console.log(response.content);
```

### Create an MCP Server (1 function!)

```typescript
import { createMCPServer } from "mcp-agent-kit";

const server = createMCPServer({
  name: "my-server",
  tools: [
    {
      name: "get_weather",
      description: "Get weather for a location",
      inputSchema: {
        type: "object",
        properties: {
          location: { type: "string" },
        },
      },
      handler: async ({ location }) => {
        return `Weather in ${location}: Sunny, 72°F`;
      },
    },
  ],
});

await server.start();
```

### Create a Chatbot with Memory

```typescript
import { createChatbot, createAgent } from "mcp-agent-kit";

const bot = createChatbot({
  agent: createAgent({ provider: "openai" }),
  system: "You are a helpful assistant",
  maxHistory: 10,
});

await bot.chat("Hi, my name is John");
await bot.chat("What is my name?"); // Remembers context!
```

## Documentation

### Table of Contents

- [AI Agents](#ai-agents)
- [MCP Servers](#mcp-servers)
- [LLM Router](#llm-router)
- [Chatbots](#chatbots)
- [API Requests](#api-requests)
- [Configuration](#configuration)
- [Examples](#examples)

---

## AI Agents

Create intelligent agents that work with multiple LLM providers.

### Basic Usage

```typescript
import { createAgent } from "mcp-agent-kit";

const agent = createAgent({
  provider: "openai",
  model: "gpt-4-turbo-preview",
  temperature: 0.7,
  maxTokens: 2000,
});

const response = await agent.chat("Explain TypeScript");
console.log(response.content);
```

### Supported Providers

| Provider      | Models               | API Key Required |
| ------------- | -------------------- | ---------------- |
| **OpenAI**    | GPT-4, GPT-3.5       | ✅ Yes           |
| **Anthropic** | Claude 3.5, Claude 3 | ✅ Yes           |
| **Gemini**    | Gemini 2.0+          | ✅ Yes           |
| **Ollama**    | Local models         | ❌ No            |

### With Tools (Function Calling)

```typescript
const agent = createAgent({
  provider: "openai",
  tools: [
    {
      name: "calculate",
      description: "Perform calculations",
      parameters: {
        type: "object",
        properties: {
          operation: { type: "string", enum: ["add", "subtract"] },
          a: { type: "number" },
          b: { type: "number" },
        },
        required: ["operation", "a", "b"],
      },
      handler: async ({ operation, a, b }) => {
        return operation === "add" ? a + b : a - b;
      },
    },
  ],
});

const response = await agent.chat("What is 15 + 27?");
```

### With System Prompt

```typescript
const agent = createAgent({
  provider: "anthropic",
  system: "You are an expert Python developer. Always provide code examples.",
});
```

### Smart Tool Calling

Smart Tool Calling adds reliability and performance to tool execution with automatic retry, timeout, and caching.

#### Basic Configuration

```typescript
const agent = createAgent({
  provider: "openai",
  toolConfig: {
    forceToolUse: true,      // Force model to use tools
    maxRetries: 3,           // Retry up to 3 times on failure
    toolTimeout: 30000,      // 30 second timeout
    onToolNotCalled: "retry", // Action when tool not called
  },
  tools: [...],
});
```

#### With Caching

```typescript
const agent = createAgent({
  provider: "openai",
  toolConfig: {
    cacheResults: {
      enabled: true,
      ttl: 300000,    // Cache for 5 minutes
      maxSize: 100,   // Store up to 100 results
    },
  },
  tools: [...],
});
```

#### Direct Tool Execution

```typescript
// Execute a tool directly with retry and caching
const result = await agent.executeTool("get_weather", {
  location: "San Francisco, CA",
});
```

#### Configuration Options

| Option                 | Type    | Default | Description                                                    |
| ---------------------- | ------- | ------- | -------------------------------------------------------------- |
| `forceToolUse`         | boolean | false   | Force the model to use tools when available                    |
| `maxRetries`           | number  | 3       | Maximum retry attempts on tool failure                         |
| `onToolNotCalled`      | string  | "retry" | Action when tool not called: "retry", "error", "warn", "allow" |
| `toolTimeout`          | number  | 30000   | Timeout for tool execution (ms)                                |
| `cacheResults.enabled` | boolean | true    | Enable result caching                                          |
| `cacheResults.ttl`     | number  | 300000  | Cache time-to-live (ms)                                        |
| `cacheResults.maxSize` | number  | 100     | Maximum cached results                                         |
| `debug`                | boolean | false   | Enable debug logging                                           |

#### Complete Example

```typescript
const agent = createAgent({
  provider: "openai",
  model: "gpt-4-turbo-preview",
  toolConfig: {
    forceToolUse: true,
    maxRetries: 3,
    onToolNotCalled: "retry",
    toolTimeout: 30000,
    cacheResults: {
      enabled: true,
      ttl: 300000,
      maxSize: 100,
    },
    debug: true,
  },
  tools: [
    {
      name: "get_weather",
      description: "Get current weather for a location",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string" },
        },
        required: ["location"],
      },
      handler: async ({ location }) => {
        // Your weather API logic
        return { location, temp: 72, condition: "Sunny" };
      },
    },
  ],
});

// Use in chat - tools are automatically called
const response = await agent.chat("What's the weather in NYC?");

// Or execute directly with retry and caching
const result = await agent.executeTool("get_weather", {
  location: "New York, NY",
});
```

---

## MCP Servers

Create Model Context Protocol servers to expose tools and resources.

### Basic MCP Server

```typescript
import { createMCPServer } from "mcp-agent-kit";

const server = createMCPServer({
  name: "my-mcp-server",
  port: 7777,
  logLevel: "info",
});

await server.start(); // Starts on stdio by default
```

### With Tools

```typescript
const server = createMCPServer({
  name: "weather-server",
  tools: [
    {
      name: "get_weather",
      description: "Get current weather",
      inputSchema: {
        type: "object",
        properties: {
          location: { type: "string" },
          units: { type: "string", enum: ["celsius", "fahrenheit"] },
        },
        required: ["location"],
      },
      handler: async ({ location, units = "celsius" }) => {
        // Your weather API logic here
        return { location, temp: 22, units, condition: "Sunny" };
      },
    },
  ],
});
```

### With Resources

```typescript
const server = createMCPServer({
  name: "data-server",
  resources: [
    {
      uri: "config://app-settings",
      name: "Application Settings",
      description: "Current app configuration",
      mimeType: "application/json",
      handler: async () => {
        return JSON.stringify({ version: "1.0.0", env: "production" });
      },
    },
  ],
});
```

### WebSocket Transport

```typescript
const server = createMCPServer({
  name: "ws-server",
  port: 8080,
});

await server.start("websocket"); // Use WebSocket instead of stdio
```

---

## LLM Router

Route requests to different LLMs based on intelligent rules.

### Basic Router

```typescript
import { createLLMRouter } from "mcp-agent-kit";

const router = createLLMRouter({
  rules: [
    {
      when: (input) => input.length  input.includes("code"),
      use: { provider: "anthropic", model: "claude-3-5-sonnet-20241022" },
    },
    {
      default: true,
      use: { provider: "openai", model: "gpt-4-turbo-preview" },
    },
  ],
});

const response = await router.route("Write a function to sort an array");
```

### With Fallback and Retry

```typescript
const router = createLLMRouter({
  rules: [...],
  fallback: {
    provider: 'openai',
    model: 'gpt-4-turbo-preview'
  },
  retryAttempts: 3,
  logLevel: 'debug'
});
```

### Router Statistics

```typescript
const stats = router.getStats();
console.log(stats);
// { totalRules: 3, totalAgents: 2, hasFallback: true }

const agents = router.listAgents();
console.log(agents);
// ['openai:gpt-4-turbo-preview', 'anthropic:claude-3-5-sonnet-20241022']
```

---

## Chatbots

Create conversational AI with automatic memory management.

### Basic Chatbot

```typescript
import { createChatbot, createAgent } from "mcp-agent-kit";

const bot = createChatbot({
  agent: createAgent({ provider: "openai" }),
  system: "You are a helpful assistant",
  maxHistory: 10,
});

await bot.chat("Hi, I am learning TypeScript");
await bot.chat("Can you help me with interfaces?");
await bot.chat("Thanks!");
```

### With Router

```typescript
const bot = createChatbot({
  router: createLLMRouter({ rules: [...] }),
  maxHistory: 20
});
```

### Memory Management

```typescript
// Get conversation history
const history = bot.getHistory();

// Get statistics
const stats = bot.getStats();
console.log(stats);
// {
//   messageCount: 6,
//   userMessages: 3,
//   assistantMessages: 3,
//   oldestMessage: Date,
//   newestMessage: Date
// }

// Reset conversation
bot.reset();

// Update system prompt
bot.setSystemPrompt("You are now a Python expert");
```

---

## API Requests

Simplified HTTP requests with automatic retry and timeout.

### Basic Request

```typescript
import { api } from "mcp-agent-kit";

const response = await api.get("https://api.example.com/data");
console.log(response.data);
```

### POST Request

```typescript
const response = await api.post(
  "https://api.example.com/users",
  { name: "John", email: "john@example.com" },
  {
    name: "create-user",
    headers: { "Content-Type": "application/json" },
  }
);
```

### With Retry and Timeout

```typescript
const response = await api.request({
  name: "important-request",
  url: "https://api.example.com/data",
  method: "GET",
  timeout: 10000, // 10 seconds
  retries: 5, // 5 attempts
  query: { page: 1, limit: 10 },
});
```

### All HTTP Methods

```typescript
await api.get(url, config);
await api.post(url, body, config);
await api.put(url, body, config);
await api.patch(url, body, config);
await api.delete(url, config);
```

---

## Configuration

### Environment Variables

All configuration is optional. Set these environment variables or pass them in code:

```bash
# MCP Server
MCP_SERVER_NAME=my-server
MCP_PORT=7777

# Logging
LOG_LEVEL=info  # debug | info | warn | error

# LLM API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
OLLAMA_HOST=http://localhost:11434
```

### Using .env File

```bash
# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
LOG_LEVEL=debug
```

The package automatically loads `.env` files using `dotenv`.

---

## Examples

Check out the `/examples` directory for complete working examples:

- `basic-agent.ts` - Simple agent usage
- `smart-tool-calling.ts` - Smart tool calling with retry and caching
- `mcp-server.ts` - MCP server with tools and resources
- `mcp-server-websocket.ts` - MCP server with WebSocket
- `llm-router.ts` - Intelligent routing between LLMs
- `chatbot-basic.ts` - Chatbot with conversation memory
- `chatbot-with-router.ts` - Chatbot using router
- `api-requests.ts` - HTTP requests with retry

### Running Examples

```bash
# Install dependencies
npm install

# Run an example
npx ts-node examples/basic-agent.ts
```

---

## API Reference

### Agent API

#### `createAgent(config: AgentConfig)`

Creates a new AI agent instance.

**Parameters:**

- `provider` (required): LLM provider - "openai", "anthropic", "gemini", or "ollama"
- `model` (optional): Model name (defaults to provider's default)
- `temperature` (optional): Sampling temperature 0-2 (default: 0.7)
- `maxTokens` (optional): Maximum tokens in response (default: 2000)
- `apiKey` (optional): API key (reads from env if not provided)
- `tools` (optional): Array of tool definitions
- `system` (optional): System prompt
- `toolConfig` (optional): Smart tool calling configuration

**Returns:** Agent instance

**Methods:**

- `chat(message: string): Promise` - Send a message and get response
- `executeTool(name: string, params: any): Promise` - Execute a tool directly

#### `AgentResponse`

Response object from agent.chat():

```typescript
{
  content: string;           // Response text
  toolCalls?: Array;
  usage?: {                  // Token usage
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
}
```

### MCP Server API

#### `createMCPServer(config: MCPServerConfig)`

Creates a new MCP server instance.

**Parameters:**

- `name` (optional): Server name (default: from env or "mcp-server")
- `port` (optional): Port number (default: 7777)
- `logLevel` (optional): Log level - "debug", "info", "warn", "error"
- `tools` (optional): Array of tool definitions
- `resources` (optional): Array of resource definitions

**Returns:** MCP Server instance

**Methods:**

- `start(transport?: "stdio" | "websocket"): Promise` - Start the server

### Router API

#### `createLLMRouter(config: LLMRouterConfig)`

Creates a new LLM router instance.

**Parameters:**

- `rules` (required): Array of routing rules
- `fallback` (optional): Fallback provider configuration
- `retryAttempts` (optional): Number of retry attempts (default: 3)
- `logLevel` (optional): Log level

**Returns:** Router instance

**Methods:**

- `route(input: string): Promise` - Route input to appropriate LLM
- `getStats(): object` - Get router statistics
- `listAgents(): string[]` - List all configured agents

### Chatbot API

#### `createChatbot(config: ChatbotConfig)`

Creates a new chatbot instance with conversation memory.

**Parameters:**

- `agent` or `router` (required): Agent or router instance
- `system` (optional): System prompt
- `maxHistory` (optional): Maximum messages to keep (default: 10)

**Returns:** Chatbot instance

**Methods:**

- `chat(message: string): Promise` - Send message with context
- `getHistory(): ChatMessage[]` - Get conversation history
- `getStats(): object` - Get conversation statistics
- `reset(): void` - Clear conversation history
- `setSystemPrompt(prompt: string): void` - Update system prompt

### API Request Helpers

#### `api.request(config: APIRequestConfig)`

Make HTTP request with retry and timeout.

**Parameters:**

- `name` (optional): Request name for logging
- `url` (required): Request URL
- `method` (optional): HTTP method (default: "GET")
- `headers` (optional): Request headers
- `query` (optional): Query parameters
- `body` (optional): Request body
- `timeout` (optional): Timeout in ms (default: 30000)
- `retries` (optional): Re

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dominiquekossi](https://github.com/dominiquekossi)
- **Source:** [dominiquekossi/mcp-agent-kit](https://github.com/dominiquekossi/mcp-agent-kit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-dominiquekossi-mcp-agent-kit
- Seller: https://agentstack.voostack.com/s/dominiquekossi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.