Matimo — Toolbox For AI Agents

Matimo is a universal, configuration‑driven AI tools ecosystem. Define tools once in YAML and reuse them across the SDK, LangChain, custom agents, and a single MCP server, without re‑implementing schemas or fragmenting integration logic.

Define once → Plug into any agent ecosystem.

📖 Documentation · 🚀 Quick Start · 📚 API Reference · 🛠️ Add Tools · 🤖 Examples

Quick Start

Installation

npm install matimo
# OR auto-discover tools from node_modules/@matimo/*
npm install matimo @matimo/slack @matimo/gmail

Minimal Example (TypeScript)

import { MatimoInstance } from '@matimo/core';

const matimo = await MatimoInstance.init({
  autoDiscover: true,
});

const result = await matimo.execute('slack_send_channel_message', {
  channel: '#general',
  text: 'Hello from Matimo!',
});

See Three Integration Patterns and examples/ for more.

What's Included

Matimo ships with built-in support for:

• Core Tools: File I/O, Web fetch, Command execution, Code search
• MCP Server: Expose all tools via stdio or Streamable HTTP to Claude Desktop, Cursor, Windsurf, and any MCP client (npx matimo mcp)
• Slack Integration: Send messages, manage channels, reactions, threads, DMs
• Gmail Integration: Send/read email, manage threads, drafts
• GitHub Integration: Issues, pull requests, releases, code search
• Notion Integration: Pages, databases, blocks, search
• HubSpot Tools: Contacts, companies, deals, tickets
• Postgres Tools: Query/modify data with safety checks
• Twilio Tools: Send SMS/MMS, manage messages
• Mailchimp Tools: Audiences, subscribers, email campaigns
• Auto-Discovery: Automatic detection of @matimo/* providers from npm
• Matimo CLI: Tool discovery, setup wizard, MCP config generation
• OAuth2 Support: Provider-agnostic authorization for Slack, Gmail, GitHub, etc.
• Framework Support: Factory pattern, Decorator pattern, LangChain, CrewAI
• TypeScript SDK: Full type safety and IDE support
• Agent Skills System: SKILL.md knowledge files with semantic search, content chunking, and progressive disclosure
• Policy Engine: 9 security rules, HITL quarantine, hot-reload, SHA-256 integrity tracking, HMAC approvals, audit events

Why Matimo?

The Problem: Every AI framework (LangChain, CrewAI, custom agents, etc.) defines tools differently. You duplicate tool logic across frameworks.

The Solution: Define tools once in clean YAML, use them everywhere — with built-in:

• TypeScript SDK (factory & decorator patterns)
• LangChain integration (with examples)
• Matimo CLI (tool discovery & management)
• Auto-discovery from npm packages
• OAuth2 support + parameter validation

See Contributing for details.

Three Integration Patterns

1️⃣ Factory Pattern (Simplest)

const matimo = await MatimoInstance.init({ autoDiscover: true });
const result = await matimo.execute('calculator', { operation: 'add', a: 5, b: 3 });

2️⃣ Decorator Pattern (Class-Based)

@tool('slack_send_channel_message')
async sendMessage(channel: string, text: string) { /* Auto-executed */ }

3️⃣ LangChain Integration

const tools = matimo.listTools().map(tool => ({
  type: 'function',
  function: { name: tool.name, description: tool.description, ... }
}));

4️⃣ MCP Server (Claude Desktop, Cursor, Windsurf, any MCP client)

# Expose all installed @matimo/* tools via MCP in one command
npx matimo mcp

# Run the setup wizard to get a ready-to-paste client config
npx matimo mcp setup

# HTTP mode for remote access / Docker
npx matimo mcp --transport http --port 3000 --self-signed

See MCP Docs for the full reference.

See SDK Usage Patterns, LangChain Integration, and MCP Server for details.

Installation

From npm (Recommended)

npm install matimo

# Install tool providers
npm install @matimo/slack @matimo/gmail

Then use with auto-discovery:

const matimo = await MatimoInstance.init({ autoDiscover: true });

Matimo CLI (Tool Management)

npm install -g @matimo/cli

matimo list      # Show installed packages
matimo search email  # Find tools
matimo install slack # Install tools

See CLI Docs for full reference.

From Source (Contributors)

git clone https://github.com/tallclub/matimo
cd matimo && pnpm install && pnpm build
pnpm test
cd examples/tools && pnpm install && pnpm agent:factory

Skills System

Matimo supports the Agent Skills specification — structured knowledge files (SKILL.md) that teach agents domain expertise at runtime.

// Discover available skills (Level 1 — metadata only)
const skills = matimo.listSkills();

// Load a specific skill (Level 2 — full content)
const skill = matimo.getSkill('slack');

// Load only the sections you need (smart context management)
const content = matimo.getSkillContent('postgres', {
  sections: ['Error Handling', 'Parameterized Queries'],
  maxTokens: 500,
});

// Semantic search across all skills
const results = await matimo.semanticSearchSkills('How do I handle rate limiting?');

Each provider ships one skill with domain knowledge for all its tools. Agents load skills on demand — no context bloat.

See Skills Documentation for the full guide.

Policy Engine & HITL

Matimo includes a defense-in-depth policy engine for agent tool usage:

const matimo = await MatimoInstance.init({
  toolPaths: ['./tools', './agent-tools'],
  policyFile: './policy.yaml', // 9 security rules, domain allowlists
  untrustedPaths: ['./agent-tools'], // Agent-created tools validated here
  onHITL: async (request) => {
    // Human-in-the-loop quarantine
    console.log(`Approve ${request.toolName}? Risk: ${request.riskLevel}`);
    return promptUser();
  },
  onEvent: (event) => auditLog.push(event),
});

// Hot-reload policy at runtime (no restart needed)
await matimo.reloadPolicy('./policy-prod.yaml');

Key features:

• 9 deterministic security rules (SSRF detection, namespace protection, credential allowlists)
• HITL quarantine — medium-risk tools pause for human approval instead of auto-rejecting
• Policy hot-reload — swap policies at runtime with automatic tool re-validation
• SHA-256 integrity tracking + HMAC approval manifest
• Full audit trail via structured events

See Policy & Lifecycle Docs for the complete reference.

Features Coming Soon:

• More tool providers (Stripe, Jira, Linear, etc.)
• Python SDK
• Custom Tool Marketplace

Adding Tools to Matimo

If you build @matimo/ following this pattern, we’ll list it in the official docs and README with you as maintainer.

Create tool providers as independent npm packages:

mkdir packages/github
cd packages/github && cat > package.json << 'EOF'
{ "name": "@matimo/github", "type": "module", ... }
EOF

mkdir tools/github-create-issue
cat > tools/github-create-issue/definition.yaml << 'EOF'
name: github-create-issue
parameters:
  owner: { type: string, required: true }
  repo: { type: string, required: true }
  title: { type: string, required: true }
execution:
  type: http
  method: POST
  url: https://api.github.com/repos/{owner}/{repo}/issues
  headers:
    Authorization: "Bearer {GITHUB_TOKEN}"
EOF

Then publish to npm as @matimo/github. Users install and auto-discover:

npm install @matimo/github
# New tools automatically available!
const matimo = await MatimoInstance.init({ autoDiscover: true });

See Adding Tools to Matimo for the complete 6-step guide.

Documentation

• Getting Started
• API Reference
• Skills System
• Policy Engine & Tool Lifecycle
• LangChain Integration
• Tool Development
• Architecture Overview
• Contributing

License

MIT © 2026 Matimo Contributors

Support the Project

• ⭐ Star the repo
• 🐛 Open issues for bugs or features
• 🔀 Submit PRs (see Contributing) Best way to help: add a new provider (Notion, Jira, Stripe, Twilio…) or expand existing toolsets.
• 📢 Share on Twitter, Reddit, Discord

Contributors

Star History