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

Matimo (Maximum AI Tools in Modular Objects) — Define tools once in YAML, use them everywhere.

Built to solve the universal tool orchestration problem for AI agents.

Complete documentation for Matimo.

Getting Started

Reference

Project Information

Development

Quick Navigation

For First-Time Users

  1. Start with Quick Start for setup
  2. Try Your First Tool to create a tool
  3. Check API Reference for SDK usage
  4. See Tool Specification to write tools
  5. Review Architecture Overview to understand design

For Tool Writers

  1. Read Tool Specification for YAML tools
  2. Or use Decorator Guide for TypeScript tools
  3. See Adding Tools to Matimo to publish packages
  4. Follow Development Standards for code quality

For Framework Integration

  1. Check Framework Integrations for LangChain/CrewAI
  2. See Architecture Overview for integration patterns
  3. Review examples in examples/ directory

For Contributors

  1. Check Contributing Guidelines for contribution guidelines
  2. Follow Development Standards for code quality
  3. Use Commit Guidelines for proper commit format

For Maintainers

  1. Review Development Standards for quality metrics
  2. Check Commit Guidelines for PR commit validation
  3. See Contributing Guidelines for overall workflow

Documentation Structure

docs/
├── index.md                      # This file - documentation index
├── RELEASES.md                   # Release notes and changelog
├── ROADMAP.md                    # Project roadmap
├── getting-started/
│   ├── QUICK_START.md            # 5-minute setup guide
│   ├── installation.md           # Detailed installation instructions
│   └── YOUR_FIRST_TOOL.md        # Create your first tool
├── api-reference/
│   ├── SDK.md                    # Complete SDK API
│   ├── ERRORS.md                 # Error handling and error codes
│   └── TYPES.md                  # TypeScript type definitions
├── tool-development/
│   ├── TOOL_SPECIFICATION.md     # YAML tool schema
│   ├── YAML_TOOLS.md             # YAML tool writing guide
│   ├── ADDING_TOOLS.md           # Creating tool packages
│   ├── DECORATOR_GUIDE.md        # TypeScript decorators
│   ├── TESTING.md                # Testing tools
│   ├── PROVIDER_CONFIGURATION.md # Multi-provider setup
│   └── OAUTH_LINK.md             # OAuth authentication
├── framework-integrations/
│   └── LANGCHAIN.md              # LangChain & framework patterns
├── architecture/
│   ├── OVERVIEW.md               # System design and patterns
│   └── OAUTH.md                  # OAuth2 implementation
├── user-guide/
│   ├── SDK_PATTERNS.md           # SDK usage patterns
│   ├── TOOL_DISCOVERY.md         # Discovering tools
│   ├── AUTHENTICATION.md         # Authentication setup
│   └── DEVELOPMENT_STANDARDS.md  # Code quality rules
├── community/
│   └── COMMIT_GUIDELINES.md      # Conventional commits
└── troubleshooting/
    └── FAQ.md                    # Common questions & solutions

Root-level files:
├── [CONTRIBUTING.md](https://github.com/tallclub/matimo/blob/main/CONTRIBUTING.md) — Contribution guidelines
├── [SECURITY.md](https://github.com/tallclub/matimo/blob/main/SECURITY.md) — Security policy
└── [README.md](https://github.com/tallclub/matimo/blob/main/README.md) — Project overview

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

Use the Matimo SDK (TypeScript) to load and execute tools:

import { MatimoInstance } from 'matimo';

const matimo = await MatimoInstance.init('./tools');
const result = await matimo.execute('tool-name', { param: 'value' });

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:

// MCP Server - Coming in Phase 2
// import { MCPServer } from 'matimo/mcp';

const server = new MCPServer({ toolsPath: './tools', port: 3000 });
await server.start();

See Quick Start for setup.

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/provider/tool-name.yaml
  2. Follow Tool Specification schema
  3. Include parameters, execution, output_schema
  4. Add authentication if needed
  5. Test with pnpm test

Write a Decorator Tool

  1. Create src/tools/tool-name.tool.ts
  2. Use @tool and @param decorators
  3. Implement execute() or async execute()
  4. Follow Decorator Guide patterns
  5. Add unit tests

Integrate with LangChain

  1. See Framework Integrations for patterns
  2. Check examples/tools/ 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: February 2026