Mochikit

🍡 MochiKit

A modern, plugin-driven TypeScript AI Agent framework.

🇨🇳 中文文档

=18">

---

> 🧠 Core philosophy: The complexity is in the harness, not the model. Every mechanism hangs off the same LLM → tool_use → results → repeat loop.

---

Why MochiKit?

MochiKit is a superbly concise Node.js AI Agent framework. Compared to mainstream alternatives, it has extremely few core files and is remarkably easy to get started. The source code comes with comprehensive English annotations, making it an excellent introductory project for learning AI Agent architecture.

| | MochiKit | LangChain | CrewAI | AutoGen | |---|---|---|---|---| | Core files | 44 | 300+ | 200+ | 250+ | | Total source lines | ~9,600 | 100,000+ | 50,000+ | 80,000+ | | Dependencies | 3 | 20+ | 15+ | 10+ | | Learning curve | 1 day | 2 weeks | 1 week | 1 week | | TypeScript strict | ✅ Zero any | ❌ | ❌ | ❌ | | Code annotations | ✅ Full JSDoc | ❌ | ❌ | Partial |

---

Features

• 🤖 Multi-Agent Collaboration — Manager-Worker delegation, Sequential Chains, Team mailbox communication with protocol state machine
• 🔌 Plugin Architecture — Bundle tools + hooks + permission rules into reusable plugins; install with agent.use(plugin)
• 📋 Skill Loading — Declarative SKILL.md files; two-level loading (catalog in system prompt, full content on demand)
• 🧠 Unified Memory — Memory interface with Markdown file storage (YAML frontmatter + index); auto-injection; consolidation/merge
• 🪝 Lifecycle Hooks — UserPromptSubmit, PreToolUse, PostToolUse, Stop — priority-ordered, async, can block or rewrite
• 🔐 Permission Pipeline — 3-gate pipeline: deny → rule → ask → resolver; built-in AllowAllResolver / DenyAllResolver
• 📦 Built-in Tools — File I/O, Bash (sync + background), Web Search, Web Reader, TodoWrite, Memory, Task DAG, Team messaging
• 🔌 MCP Server Compatibility — Connect to MCP servers via stdio or Streamable HTTP; tools are auto-discovered and namespaced as mcp____
• ⚡ Background Tasks — Long-running bash commands run asynchronously; agent continues working
• 🛡️ Error Recovery — Exponential backoff + jitter for 429/529, reactive compaction on prompt_too_long, fallback model failover
• 🌐 Multi-Provider — Configure multiple LLM providers (GLM, OpenAI, Anthropic, DeepSeek…) in one .env; select per-agent via loadConfig('provider')
• 📐 Strict TypeScript — Zero any, full type safety, OOP + dependency injection throughout
• 🧪 Fully Tested — 135 unit tests (mock LLM) + 18 integration tests (real GLM)

---

Installation

git clone https://github.com/MochiKit/MochiKit.git
cd MochiKit
npm install
cp .env.example .env   # Edit .env with your API key

.env — MochiKit uses the Anthropic-compatible protocol. Default endpoint is GLM (Zhipu):

BASE_URL=https://open.bigmodel.cn/api/anthropic
API_KEY=your-api-key-here
MODEL=glm-4.7
MOCHIKIT_WEB_API_KEY=your-api-key-here
MOCHIKIT_RUN_INTEGRATION=0

> 💡 Any Anthropic-compatible endpoint works — just change BASE_URL and MODEL.

Multi-Provider Configuration

Configure multiple LLM providers side-by-side using the {NAME}_API_KEY naming convention:

# Default provider (no prefix)
API_KEY=your-glm-key
BASE_URL=https://open.bigmodel.cn/api/anthropic
MODEL=glm-4.7

# Named providers
DEEPSEEK_API_KEY=sk-your-deepseek-key
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
DEEPSEEK_MODEL=deepseek-chat

OPENAI_API_KEY=sk-your-openai-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o

Select a provider when loading config:

import { loadConfig } from 'mochikit';

const glmCfg    = loadConfig();           // default provider
const deepCfg   = loadConfig('deepseek'); // DeepSeek
const openaiCfg = loadConfig('openai');   // OpenAI

MCP Server Integration

Connect to Model Context Protocol (MCP) servers and use their tools directly in your agents:

import { Agent, createMCPPlugin, AnthropicAdapter, loadConfig, PermissionManager, AllowAllResolver } from 'mochikit';

const cfg = loadConfig();

// Configure MCP servers — tools are auto-discovered
const mcp = createMCPPlugin({
  servers: [
    {
      name: 'filesystem',
      transport: {
        type: 'stdio',
        command: 'npx',
        args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
      },
      permissionMode: 'auto-allow', // trust this server's tools
    },
  ],
});

const agent = new Agent({
  name: 'mcp-demo',
  llm: new AnthropicAdapter({ apiKey: cfg.apiKey, baseURL: cfg.baseUrl }),
  model: cfg.model,
  systemPrompt: 'You have access to filesystem tools via MCP.',
  permission: new PermissionManager({ resolver: new AllowAllResolver() }),
});

agent.use(mcp.plugin);         // Install MCP tools
await mcp.init();               // Wait for connections (optional)

console.log(await agent.run('List files in /tmp'));

Tools are namespaced as mcp__filesystem__read_file, mcp__filesystem__list_directory, etc. — no collisions with built-in tools. Supports both stdio (local subprocess) and Streamable HTTP (remote server) transports.

---

Quick Start

import {
  Agent, AnthropicAdapter, loadConfig,
  createBashTool, AllowAllResolver, PermissionManager,
} from 'mochikit';

const cfg = loadConfig();

const agent = new Agent({
  name: 'demo',
  llm: new AnthropicAdapter({ apiKey: cfg.apiKey, baseURL: cfg.baseUrl }),
  model: cfg.model,
  systemPrompt: 'You are a helpful assistant. Be concise.',
  tools: [createBashTool()],
  permission: new PermissionManager({ resolver: new AllowAllResolver() }),
});

console.log(await agent.run('List the files in the current directory'));

Run it:

npx tsx your-file.ts

More examples:

npx tsx docs/examples/01-simple-agent.ts       # Single agent + file/bash tools
npx tsx docs/examples/02-manager-worker.ts     # Manager-Worker collaboration
npx tsx docs/examples/03-sequential-chain.ts   # Sequential chain + shared memory
npx tsx docs/examples/04-memory-and-vector.ts  # Markdown memory + vector store
npx tsx docs/examples/05-custom-plugin.ts      # Custom plugin: tools + hooks + rules

---

Architecture

The AgentLoop is the heart of the framework:

User Input → [UserPromptSubmit hooks] → while (turns 
  Built with ❤️ using TypeScript · Anthropic SDK · GLM · Vitest

## Source & license

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

- **Author:** [narrastory](https://github.com/narrastory)
- **Source:** [narrastory/mochikit](https://github.com/narrastory/mochikit)
- **License:** MIT

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