View on GitHub

Matimo - AI Tools Ecosystem

Define tools once in YAML, use them everywhere

Download this project as a .zip file Download this project as a tar.gz file

Matimo Documentation

Matimo Logo

Discord

Matimo — Enable AI Agents To Build Themselves

Open-source tool governance for AI agents: every call risk-checked, every risky one approved by a human, every result on a log you can verify

Give your agents 129 production-ready tools to start (plus a governed 449-tool Composio catalog). Then activate 15 meta-tools that let them create, validate, and approve new capabilities at runtime — governed by your policy engine with human approval workflows for critical actions.

Self-extending agents with enterprise-grade control:

New here? Read Why Matimo OSS and what changed in 0.2.0.

Complete documentation for Matimo 0.3.0 (TypeScript @matimo/core 0.3.0 and Python matimo 0.2.0).

New in 0.3.0: Node 22.19+ is now required, and the open security advisories are patched. See the release notes.

Since 0.2.0 — secure by default. HTTP DELETE and command tools ask a human before every call, each instance has its own approval callback (onApproval), MCP servers ask the client’s user through elicitation, every call emits events you can keep in a tamper-evident audit log, and both SDKs enforce the same rules. Upgrading? Read the migration guide.

🚀 Choose Your SDK

🟦 TypeScript / Node.js

🐍 Python 🎉 Stable Release

⚡ Getting Started

TypeScript Getting Started

  1. Quick Start — 5-minute setup
  2. Your First Tool — Create a basic YAML tool
  3. API Reference — SDK fundamentals

Python Getting Started

  1. Quick Start — 5-minute setup with pip install matimo
  2. LangChain Integration — Build ReAct agents
  3. CrewAI Integration — Multi-agent orchestration
  4. Agno Integration — Governed Agno agents, teams and workflows
  5. API Reference — Python SDK documentation

📦 Installation & Requirements

📚 Reference (By Topic)

🟢 Core Concepts (Start Here)

🟡 Tool Development

🛡️ Policy & Lifecycle (Security)

🔴 Advanced Topics

Project Information

👥 For Contributors

Want to contribute? Start here:

  1. Contributing Guidelines — Full contribution workflow
    • Setup and development environment
    • Code standards and best practices
    • TDD (Test-Driven Development) approach
    • Commit message format
    • PR checklist
  2. Commit Guidelines — Conventional commits standard
    • Type, scope, subject format
    • Examples for feat, fix, docs, etc.
    • Git workflow tips
  3. Development Standards — Code quality requirements
    • TypeScript strictness
    • Testing coverage (TypeScript floors enforced; Python informational)
    • ESLint / ruff and Prettier
    • JSDoc documentation

Development & Advanced Usage

Troubleshooting

Quick Navigation by Role

🚀 Just Getting Started (First 30 minutes)

  1. Quick Start — Install and run your first tool
  2. Your First Tool — Create a basic YAML tool
  3. API Reference — Understand the SDK basics
  4. If stuck → FAQ

🛠️ Building Tools

  1. Tool Specification — YAML schema reference
  2. Adding Tools to Matimo — Publish a package
  3. Testing Tools — Write tests
  4. OAuth Setup — Add authentication

🤖 Integrating with Frameworks (LangChain, CrewAI, etc.)

  1. Architecture Overview — Understand patterns
  2. Framework Integrations — Integration examples
  3. SDK Patterns — Best practices

🔒 Securing Agent Tool Usage

  1. Policy & Lifecycle Guide — Full security setup
  2. Meta-Tools Reference — Built-in management tools
  3. Approval System — Approval handler config
  4. Policy Demo (Python) — 11-mission autonomous agent demo
  5. Policy Demo (TypeScript) — TypeScript equivalent
  6. Skills Demo (Python) — 6-mission skills lifecycle demo

🤖 For AI Agents (Quick Orientation)

If you are an AI agent (LangChain, CrewAI, MCP client) reading this to understand Matimo:

  1. Read first: Meta-Tools Reference — the 15 built-in meta-tools you can call right now
  2. Tool creation flow: matimo_validate_tool → matimo_create_tool → matimo_approve_tool → matimo_reload_tools
  3. Skills discovery: matimo_list_skills → matimo_get_skill to load domain expertise on-demand
  4. OpenAI 128-tool limit: If using auto_discover=True, cap your bound tool list — prioritize matimo_* tools first
  5. Policy rules: Draft tools are blocked whenever the context environment string contains “prod” (case-insensitive substring match — "prod", "production", "PRODUCTION-us-east" all match), and in any other environment they run only for a caller with the admin role; approve a tool with matimo_approve_tool to use it normally. Command tools, HTTP DELETE tools and tools with requires_approval: true ask a human before every call. SSRF-blocked URL patterns are rejected by the content validator both at creation/approval time and again at execution time against the fully-resolved URL.
  6. Errors: All errors are MatimoError with typed ErrorCode. Check error.code for programmatic handling.
  7. Examples to study: python/examples/native/meta_flow/meta_tools_integration.py is the canonical end-to-end reference.

👨‍💻 Contributing Code

  1. Start here: Contributing Guidelines
  2. Clone repo and set up locally
  3. Commit Guidelines — Proper commit format
  4. Development Standards — Code quality rules
  5. Open PR and request review

📖 Maintaining/Reviewing

  1. Development Standards — Review checklist
  2. Contributing Guidelines — PR requirements
  3. Commit Guidelines — Validate commits
  4. Architecture Overview — Understand design decisions

Documentation Structure

docs/
├── index.md                      # This file — documentation index
├── RELEASES.md                   # Release notes and changelog
├── ROADMAP.md                    # Project roadmap
├── MCP.md                        # MCP server setup and Claude Desktop
├── COMPOSIO.md                   # Governed Composio catalog
├── mcp/                          # MCP setup, quick reference, maintenance
├── notebooks/                    # Colab notebooks (00_index … 05_mcp_server)
├── getting-started/
│   ├── QUICK_START.md            # 5-minute setup (TypeScript + Python)
│   ├── installation.md           # Detailed installation
│   └── YOUR_FIRST_TOOL.md        # Create your first tool
├── api-reference/
│   ├── SDK.md                    # Complete SDK API (TypeScript + Python)
│   ├── ERRORS.md                 # Error handling and error codes
│   ├── TYPES.md                  # TypeScript type definitions
│   ├── META_TOOLS.md             # Built-in meta-tools reference (15 tools)
│   ├── POLICY_AND_LIFECYCLE.md   # Policy engine and tool lifecycle
│   ├── APPROVAL-SYSTEM.md        # Approval handler configuration
│   └── LOGGING.md                # Logger API and formats
├── tool-development/
│   ├── TOOL_SPECIFICATION.md     # YAML tool schema reference
│   ├── YAML_TOOLS.md             # YAML tool writing guide
│   ├── ADDING_TOOLS.md           # Creating tool provider packages
│   ├── DECORATOR_GUIDE.md        # TypeScript decorators
│   ├── TESTING.md                # Testing tools
│   ├── TOOL_WORKFLOW.md          # Step-by-step tool checklist
│   ├── HTTP_PARAMETER_EMBEDDING.md # HTTP parameter encoding
│   └── PROVIDER_CONFIGURATION.md # Multi-provider setup
├── framework-integrations/
│   ├── LANGCHAIN.md              # LangChain (Python + TypeScript)
│   ├── CREWAI.md                 # CrewAI multi-agent (Python)
│   ├── AGNO.md                   # Agno agents/teams/workflows (Python)
│   ├── BRUNO.md                  # Bruno API testing
│   └── VERCEL_AI.md              # Vercel AI SDK (TypeScript)
├── skills/
│   ├── SKILLS.md                 # Skills system guide
│   └── TFIDF_SEMANTIC_SEARCH.md  # TF-IDF implementation details
├── architecture/
│   ├── OVERVIEW.md               # System design and patterns
│   └── OAUTH.md                  # OAuth2 implementation
├── user-guide/
│   ├── SDK_PATTERNS.md           # Factory, decorator, framework patterns
│   ├── TOOL_DISCOVERY.md         # Auto-discovery and search
│   ├── AUTHENTICATION.md         # API keys, OAuth2, token management
│   └── DEVELOPMENT_STANDARDS.md  # Code quality rules
├── community/
│   └── COMMIT_GUIDELINES.md      # Conventional commits
└── troubleshooting/
    └── FAQ.md                    # Common questions & solutions

Python examples (python/examples/):
├── native/                       # Factory, decorator + advanced agent demos
│   ├── policy/policy_demo.py     # 11-mission policy + HITL lifecycle
│   ├── skills/skills_demo.py     # 6-mission skills lifecycle
│   ├── meta_flow/meta_tools_integration.py  # 5-mission meta-tools lifecycle
│   └── logger_example.py         # Logging demo (no API key needed)
├── langchain/                    # LangChain agents, per provider
├── crewai/                       # CrewAI agents, per provider
├── agno/                         # Agno agents
├── bruno/                        # Bruno collections as governed tools
└── mcp/                          # MCP server and client (own uv project)

TypeScript examples (typescript/examples/tools/):
├── <provider>/                   # factory, decorator, langchain, with-approval per provider
├── policy/policy-demo.ts         # 11-mission policy lifecycle
├── skills/skills-demo.ts         # Skills lifecycle + TF-IDF
├── meta-flow/meta-tools-integration.ts  # Meta-tools lifecycle
└── agents/langchain-skills-policy-agent.ts  # Production agent pattern

Key Concepts

Tools

Tools are the building blocks of Matimo. They define what can be executed, what parameters they accept, and how they run.

Executors

Executors run tools with different backends:

See API Reference for details.

SDK

Load tools and execute them:

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

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

from matimo import Matimo

matimo = await Matimo.init(auto_discover=True)
result = await matimo.execute("calculator", {"operation": "add", "a": 2, "b": 3})

See Quick Start and API Reference.

MCP Server

Matimo can run as an MCP server, allowing Claude and other clients to discover and use tools:

npx matimo mcp                 # stdio, for Claude Desktop / Cursor

import { createMCPServer } from '@matimo/core/mcp';

const server = await createMCPServer({ transport: 'http', port: 3000, autoDiscover: true });

See MCP.md for client configuration, HTTP mode and Python.

Standards & Practices

Code Quality

See Development Standards.

Commits

See Commit Guidelines.

Pull Requests

See Contributing Guidelines.

Common Tasks

Write a YAML Tool

  1. Create tools/<tool-name>/definition.yaml (name matches the directory)
  2. Follow the Tool Specification schema
  3. Include parameters and execution; add authentication if needed
  4. Run pnpm validate-tools
  5. Follow the Tool Workflow for tests and examples in both SDKs

Write a Decorator Tool

  1. Load the YAML tool with MatimoInstance.init(...) and call setGlobalMatimoInstance(matimo)
  2. Add a class method decorated with @tool('tool-name')
  3. Calling the method executes the tool through the policy engine
  4. Follow Decorator Guide patterns

Integrate with LangChain

  1. See Framework Integrations for patterns
  2. Check typescript/examples/tools/ and python/examples/langchain/ for working examples
  3. Follow Architecture Overview for design decisions

Contribute Code

  1. Fork and clone repository
  2. Create feature branch: git checkout -b feat/description
  3. Write tests first (TDD)
  4. Implement feature
  5. Follow Development Standards
  6. Commit using Commit Guidelines
  7. Push and create PR
  8. Follow Contributing Guidelines checklist

Need Help?

Documentation Note: While I strive for accuracy and completeness, this documentation may contain oversights, outdated information, or areas needing improvement, due to my limitations. If you notice any errors, missing information, or have suggestions for enhancement, please help me to improve! See our Contributing Guidelines to learn how to submit corrections and improvements. Your contributions to documentation are highly valued! Thank you.

Last updated: October 2026