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

⬆️ Dependency Upgrade: axios ^1.15.2 → ^1.18.0

Bumped axios workspace-wide ahead of this release — applied via the pnpm.overrides block in typescript/package.json plus the direct axios dependency in core, composio, gmail, notion, microsoft, and slack. Verified axios@1.18.0 resolves consistently across every package in the workspace (including transitive consumers like cli, bruno, postgres, twilio, hubspot, github, mailchimp, and examples/tools) via the lockfile and node_modules resolution.

No code changes were required — axios 1.18 is backward-compatible with 1.15 for Matimo’s usage. Verified via:

🐛 Fix: pnpm test could run against stale/missing compiled tool files

type: function tools (e.g. @matimo/microsoft’s ms_search_knowledge, ms_read_file, ms_list_files, ms_create_document) ship as colocated .ts sources that tsc compiles in place to .js — the .js outputs are gitignored (typescript/packages/*/tools/**/*.js) and only exist after pnpm build. Running pnpm test without building first causes FunctionExecutor’s dynamic import() to fail to find those files, producing a generic (non-MatimoError) failure with result.code: undefined instead of 'VALIDATION_FAILED' — this is what surfaced as recurring, hard-to-pin-down microsoft integration test failures across releases.

CI already guarded against this with an explicit Build step (added after the v0.1.4 release for the same reason), but local pnpm test runs had no equivalent guard. Root-caused by reproducing directly: removing the compiled .js files locally reproduced the exact failure (4 failing assertions, code: undefined); rebuilding fixed it immediately.

Fix: added pretest/pretest:coverage scripts (pnpm build) to typescript/package.json, and set enable-pre-post-scripts=true in typescript/.npmrc — pnpm defaults this to false, so the lifecycle hooks were silently never firing. Verified the fix by reproducing the failure, confirming pnpm test now auto-rebuilds and passes without a manual pnpm build step first; full suite re-run clean (2185/2185) afterward.

🆕 New Package: @matimo/composio

@matimo/composio wraps Composio’s REST execute endpoint with Matimo’s full governance stack. Every Composio action becomes a schema-valid Matimo tool with explicit risk classification, policy-gated execution, and optional HITL approval — all without custom executor code.

342 generated tools across 9 toolkits:

Toolkit Tools Key actions
jira 46 get/create/update/delete issue, search JQL, manage projects
asana 84 tasks, projects, teams, portfolios, goals
linear 21 issues, cycles, projects, roadmaps
googledrive 51 upload/download/search files, manage permissions, shared drives
googlecalendar 28 create/find/list events, free/busy query, multi-calendar
outlook 43 email rules, folders, contacts, calendar, attachments
one_drive 35 files, folders, SharePoint lists, site contents, subscriptions
share_point 6 folders, lists, list items, user management
microsoft_teams 28 teams, channels, chats, messages, meetings

🏗 Generator: scripts/generate-tools.ts

A typed TypeScript script (pnpm generate:composio) that fetches a toolkit’s action catalog from Composio’s REST API and writes one definition.yaml per action — idempotent, paginated, and schema-validated on every write.

Key generator behaviors:

cd typescript/
pnpm generate:composio --toolkits=JIRA,LINEAR,GOOGLEDRIVE
pnpm generate:composio --toolkits=GOOGLEDRIVE,GOOGLECALENDAR --force-refresh
pnpm validate-tools   # 488 valid, 0 invalid

🛡 Governance Layer

DefaultPolicyEngine.canExecute() does not gate on risk: (it handles deprecation/draft/requires_approval). To enforce human approval for composio write/delete operations, applications supply a custom PolicyEngine:

class ComposioRiskPolicy implements PolicyEngine {
  canExecute(ctx, tool): PolicyDecision {
    const base = new DefaultPolicyEngine().canExecute(ctx, tool);
    if (base.allowed !== true) return base;
    const risk = classifyRisk(tool);
    if (tool.name.startsWith('composio_') && (risk === 'medium' || risk === 'high')) {
      return { allowed: 'pending_approval', riskLevel: risk, reason: '...', toolName: tool.name };
    }
    return { allowed: true };
  }
  canCreate(ctx, tool) { return new DefaultPolicyEngine().canCreate(ctx, tool); }
}

const matimo = await MatimoInstance.init({
  toolPaths: [COMPOSIO_TOOLS_DIR],
  policy: new ComposioRiskPolicy(),
  onHITL: async (req) => promptForApproval(req),
});

📚 Documentation & Examples

4 TypeScript examples in typescript/examples/tools/composio/:

🧪 Testing

@matimo/composio follows the “generated tools” testing exception (no per-tool tests or examples required):

Known Composio catalog issue: As of March 2026, Jira deprecated /rest/api/3/search. Composio’s JIRA_SEARCH_ISSUES and JIRA_SEARCH_FOR_ISSUES_USING_JQL_POST actions return HTTP 410 until Composio updates their catalog to use /rest/api/3/search/jql. All other Jira actions are unaffected.

Full workspace gate (post version bump to 0.1.5, all 13 packages): pnpm install, pnpm build, pnpm validate-tools (488/488 valid), pnpm lint (clean), pnpm test / test:coverage (2185/2185 passing, 95.24% lines / 97.53% functions) — all green.

v0.1.4 — Function-Type Tool Runtime Loading Fix & Microsoft Provider Fixes 🔧

Release: Closes the remaining “function-type tools crash at runtime for npm consumers” gap from v0.1.3 across @matimo/core, @matimo/bruno, @matimo/notion, @matimo/postgres, and @matimo/microsoft — plus Microsoft Graph bug fixes and example corrections

Released: June 11, 2026 Scope: TypeScript workspace — matimo (root), @matimo/core, @matimo/bruno, @matimo/notion, @matimo/postgres, and @matimo/microsoft bumped to v0.1.4 Severity: 🟠 Important — fixes a runtime crash for npm consumers of type: function tools in the affected packages; no breaking API changes

🐛 Bug Fix: Function-Type Tools Now Compile to .js In Place (extends v0.1.3 Issue 1)

Problem: v0.1.3 fixed @matimo/core’s built-in function-type tools (web, calculator, execute) by rewriting their imports to a runtime-safe @matimo/core/runtime subpath — but the tool files themselves still shipped as raw .ts source with code: './foo.ts' in definition.yaml. FunctionExecutor loads these via dynamic import(), which Node cannot resolve for .ts files without a transpiling loader (tsx/ts-node) — something npm consumers of @matimo/core, @matimo/bruno, @matimo/notion, @matimo/postgres, and @matimo/microsoft do not have installed. Every type: function tool in these 5 packages — built-in core tools (web, calculator, execute, read, edit, search), all 10 matimo_* meta-tools, the 7 Bruno CLI tools, the Notion page-creation tool, the Postgres SQL executor, and all 9 Microsoft Graph tools — would fail to load at runtime outside the monorepo.

Fix:

🐛 Bug Fix: Microsoft Graph $search ConsistencyLevel Header & Non-UTF-8 File Decoding

Problem 1 — ms_get_email search queries: Microsoft Graph’s $search on /me/messages requires the ConsistencyLevel: eventual header; omitting it can cause a 400 UnsupportedQuery error.

Fix: ms_get_email now injects ConsistencyLevel: eventual only when the search parameter is provided — $filter/$orderby-only queries are unaffected.

Problem 2 — ms_read_file non-UTF-8 content: The Python executor decoded file content with buffer.decode('utf-8'), which raises UnicodeDecodeError on non-UTF-8 bytes (e.g. Latin-1 encoded text/plain files). Node’s Buffer.toString() has no equivalent failure mode — it silently replaces invalid sequences — so the Python and TypeScript executors behaved differently for the same file.

Fix: Python decode now uses errors='replace', matching the TypeScript executor’s behavior. Regression tests added for both cases.

(commit b8c7cb0)

🛠 Example Fixes

📦 Version Bumps

Package Previous New Type
matimo (root) 0.1.3 0.1.4 Patch
@matimo/core 0.1.3 0.1.4 Patch
@matimo/bruno 0.1.3 0.1.4 Patch
@matimo/notion 0.1.3 0.1.4 Patch
@matimo/postgres 0.1.3 0.1.4 Patch
@matimo/microsoft 0.1.0 0.1.4 Catch-up

@matimo/microsoft jumps from 0.1.0 to 0.1.4 to align with the rest of the workspace’s release train. All other packages (slack, gmail, github, hubspot, mailchimp, twilio, cli, linkedin, medium, reddit) are unchanged in this release — they have no type: function tools affected by the build-pipeline fix above.

📊 Current Totals

🧪 Verification

🔄 Upgrade

npm install matimo@0.1.4
# or
npm update matimo

No API changes — all interfaces remain identical. Consumers of @matimo/core, @matimo/bruno, @matimo/notion, @matimo/postgres, or @matimo/microsoft who previously hit ERR_MODULE_NOT_FOUND / ERR_UNKNOWN_FILE_EXTENSION errors loading type: function tools should reinstall to pick up the compiled .js tool files.

Microsoft Graph Provider — v0.1.0 🪟

Release: New provider package — Microsoft Graph integration for search, mail, files, Teams, calendar, and SharePoint

Released: June 9, 2026 Scope: New packages only — @matimo/microsoft v0.1.0 (npm) · matimo-microsoft v0.1.0 (PyPI) Severity: 🟢 Additive — no changes to existing packages

🆕 New Provider: Microsoft Graph

9 tools covering the full Microsoft 365 surface area, using delegated OAuth2 access tokens:

Tool Description Risk Graph Endpoint
ms_search_knowledge Search SharePoint sites, OneDrive/SharePoint files, and list items low POST /search/query
ms_read_file Read a OneDrive/SharePoint file’s contents (plain-text formats) low GET /drives/{id}/items/{id}/content
ms_list_files List children of a OneDrive/SharePoint folder low GET /drives/{id}/items/{id}/children
ms_get_email List messages in the signed-in user’s mailbox low GET /me/messages
ms_send_email Send an email as the signed-in user high (approval) POST /me/messages + /send
ms_send_teams_message Post or reply to a message in a Teams channel medium POST /teams/{id}/channels/{id}/messages
ms_create_document Upload a file to OneDrive/SharePoint (≤4 MB) medium PUT /drives/{id}/items/{id}:/{name}:/content
ms_create_calendar_event Create a calendar event, optionally as a Teams meeting medium POST /me/events
ms_publish_to_sharepoint Create and publish a SharePoint site page high (approval) POST /sites/{id}/pages + /publish

ms_send_email and ms_publish_to_sharepoint are risk: high with requires_approval: true — routed through the HITL flow before execution.

🐛 Bug Fix: Retry-After Header Parsing

Problem: The Python graph_client.py called float(retry_after_header) directly when mapping 429 responses. Per RFC 9110 §10.2.3, Retry-After MAY be an HTTP-date string (e.g. Fri, 31 Dec 1999 23:59:59 GMT) rather than delta-seconds. Python’s float() raises ValueError on non-numeric input — unlike JavaScript’s Number() which returns NaN — so an HTTP-date header from a proxy or gateway would crash error mapping entirely rather than gracefully falling back to exponential backoff.

Fix: Extracted _parse_retry_after_seconds() helper that guards the conversion in a try/except (TypeError, ValueError) block, returning None on non-numeric values. The retry loop already handled None correctly (falls back to exponential backoff). Regression test added for the HTTP-date case.

📦 New Packages

Package Version Registry
@matimo/microsoft 0.1.0 npm
matimo-microsoft 0.1.0 PyPI

No existing package versions changed.

🧪 Verification

🔄 Install

# TypeScript
npm install @matimo/microsoft

# Python
pip install matimo-microsoft

Authentication: provide a delegated Microsoft Graph access token via the MICROSOFT_GRAPH_ACCESS_TOKEN environment variable or credentials parameter. Matimo never performs the OAuth exchange itself.

v0.1.3 — Tool Import & Package Hotfix 🔧

Release: Critical fix for broken runtime imports in published tool files and missing meta package README

Released: May 19, 2026
Scope: TypeScript SDK only — All packages bumped to v0.1.3
Severity: 🔴 CRITICAL — Function-type tools crash at runtime for all public npm consumers

🐛 Issue 1: Tool Files Importing from ../../src/ at Runtime

Problem:
Function-type tool files shipped under tools/ in the tarball contained imports pointing to ../../src/... — a path that does not exist in the published npm package (only dist/ is shipped):

Error [ERR_MODULE_NOT_FOUND]: Cannot find module
  '/path/to/node_modules/@matimo/core/src/errors/matimo-error'

Root Cause:
The tsconfig.json for @matimo/core only compiles src/**/* to dist/. Tool files under tools/ are shipped as raw source and loaded at runtime via dynamic import() by FunctionExecutor. These files must import from the compiled dist/ output, not the unshipped src/ tree.

Files Fixed:

Before:

import { MatimoError, ErrorCode } from '../../src/errors/matimo-error';
import { getGlobalMatimoLogger } from '../../src/logging/logger';

After:

import { MatimoError, ErrorCode, getGlobalMatimoLogger, getGlobalApprovalHandler } from '@matimo/core/runtime';

Why @matimo/core/runtime and not ../../dist/:
Tool files are shipped as raw .ts source in the npm tarball (tools/ is not compiled). They are loaded at runtime via dynamic import() by the FunctionExecutor. Two constraints apply simultaneously:

The @matimo/core/runtime subpath resolves both:

A dedicated src/runtime/index.ts entrypoint was added as a narrow export surface (only the 4 symbols built-in tools need), reducing coupling to the full package barrel.

🐛 Issue 2: Skill Tool Files Importing Shared Helper Without .js Extension

Problem:
matimo_create_skill, matimo_get_skill, and matimo_validate_skill tool files imported '../shared/skill-validation' without a .js extension. Node ESM requires explicit extensions on relative imports.

Solution:

🐛 Issue 3: Default excludePatterns in search Tool

Problem:
The search tool silently excluded dist/, build/, node_modules/, and .git/ from results by default — preventing legitimate use cases (e.g. inspecting compiled output).

Solution:
Removed all hardcoded default exclusions. The glob ignore option is now only applied when the caller explicitly provides excludePatterns. Callers who want to exclude common directories must opt in explicitly.

🐛 Issue 4: Meta matimo Package Had No README

Problem:
typescript/package.json declared "README.md" in its files array, but no typescript/README.md existed — so the matimo npm package tarball shipped with no README at all.

Solution:
Added typescript/README.md — a TypeScript-only edition of the project README with absolute GitHub URLs for all links and images (relative paths do not resolve on npmjs.com).

📦 Version Bumps

Package Previous New Type
matimo (root) 0.1.2 0.1.3 Patch
@matimo/core 0.1.2 0.1.3 Patch
@matimo/cli 0.1.2 0.1.3 Patch
@matimo/bruno 0.1.2 0.1.3 Patch
@matimo/github 0.1.2 0.1.3 Patch
@matimo/gmail 0.1.2 0.1.3 Patch
@matimo/hubspot 0.1.2 0.1.3 Patch
@matimo/linkedin 0.1.0 0.1.3 Patch
@matimo/mailchimp 0.1.2 0.1.3 Patch
@matimo/medium 0.1.0 0.1.3 Patch
@matimo/notion 0.1.2 0.1.3 Patch
@matimo/postgres 0.1.2 0.1.3 Patch
@matimo/reddit 0.1.0 0.1.3 Patch
@matimo/slack 0.1.2 0.1.3 Patch
@matimo/twilio 0.1.2 0.1.3 Patch

🧪 Verification

🔄 Upgrade

npm install matimo@0.1.3
# or
npm update matimo

No API changes — all interfaces remain identical.

v0.1.1.post1 — Meta-Package Tools Path Fix 🐛

Release: Hotfix for broken pip install matimo imports in Python SDK

Released: May 12, 2026
Scope: Python SDK only — matimo meta-package bumped to v0.1.1.post1
Severity: 🔴 CRITICAL — Breaks all public pip install matimo consumers

🐛 Issue: Empty Meta-Package __init__.py

Problem:
After pip install matimo, all import attempts failed with:

ImportError: cannot import name 'Matimo' from 'matimo'

Root Cause:
The matimo Python meta-package __init__.py was empty — it declared matimo-core as a dependency but never re-exported anything from it. Users installing matimo got an empty shell with no accessible API.

Impact:

✅ Solution: pkgutil.extend_path Namespace Merge

Updated python/packages/matimo/src/matimo/__init__.py to:

  1. Use pkgutil.extend_path(__path__, __name__) to merge the meta-package namespace with matimo-core’s files in site-packages
  2. Explicitly re-export the full public API from matimo-core submodules
  3. Include a complete __all__ matching matimo-core’s public API

Before:

# Empty — no exports at all

After:

import pkgutil
__path__ = pkgutil.extend_path(__path__, __name__)

from matimo.instance import Matimo, InitOptions, ReloadResult, matimo
from matimo import convert_tools_to_langchain
from matimo import convert_tools_to_crewai
# ... full public API (lazy wrappers — no ImportError if optional deps absent)

📦 Version Bumps

Package Previous New Type
matimo (Python meta-package) 0.1.0 0.1.1.post1 Patch

🧪 Verification

✅ Additional Improvements

v0.1.2 — TypeScript ESM Hotfix 🔧

Release: Critical fix for ES Module imports in published npm package

Released: May 7, 2026
Scope: TypeScript SDK only — All 11 packages bumped to v0.1.2
Severity: 🔴 CRITICAL — Breaks all public npm consumers

🐛 Issue: ESM Module Resolution Failure

Problem:
Published npm package (matimo@0.1.1) failed on all public consumers with:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 
  '/path/to/node_modules/@matimo/core/dist/core/schema'

Root Cause:
TypeScript compilation does not automatically add .js extensions to ES Module imports. When compiled JavaScript runs in Node.js, ESM resolution is strict and requires explicit file extensions.

Example:

// ❌ This source compiles to `dist/index.js` but breaks at runtime:
export { ToolLoader } from './core/tool-loader';  // Missing .js!

// ✅ Should compile to:
export { ToolLoader } from './core/tool-loader.js';  // Correct

Impact:

✅ Solution: Add Explicit .js Extensions

Files Fixed:

Before:

import { ToolLoader } from './core/tool-loader';
import { MatimoError } from './errors/matimo-error';
import { ApprovalHandler } from './approval/approval-handler';

After:

import { ToolLoader } from './core/tool-loader.js';
import { MatimoError } from './errors/matimo-error.js';
import { ApprovalHandler } from './approval/approval-handler.js';

When TypeScript compiles these imports, the .js extensions are preserved in the output, allowing Node.js ESM resolution to work correctly.

📦 Version Bumps

Package Previous New Type
matimo (root) 0.1.1 0.1.2 Patch
@matimo/core 0.1.0 0.1.2 Patch
@matimo/cli 0.1.0 0.1.2 Patch
@matimo/bruno 0.1.0 0.1.2 Patch
@matimo/github 0.1.0 0.1.2 Patch
@matimo/gmail 0.1.0 0.1.2 Patch
@matimo/hubspot 0.1.0 0.1.2 Patch
@matimo/mailchimp 0.1.0 0.1.2 Patch
@matimo/notion 0.1.0 0.1.2 Patch
@matimo/postgres 0.1.0 0.1.2 Patch
@matimo/slack 0.1.0 0.1.2 Patch
@matimo/twilio 0.1.0 0.1.2 Patch

🧪 Verification

📝 Why This Happened

TypeScript Compilation Behavior: TypeScript’s tsc compiler is format-preserving for import statements. When you write import { X } from './x', the compiler outputs import { X } from './x' (no automatic .js addition).

CJS vs ESM:

Local Development vs npm:

Best Practice Going Forward: Always add .js extensions explicitly in TypeScript when targeting ESM + npm distribution.

🔄 Next Steps for Users

Immediate:

npm install matimo@0.1.2  # New hotfix version
# or
npm update matimo

Local Development: Continue using local source — no changes needed. TypeScript compilation still works correctly.

Migration: No code changes required — the fix is transparent. All APIs remain identical.

v0.1.0 — First Stable Release 🎉

Release: Production-Ready AI Tools SDK — Full-Stack TypeScript & Python with 137+ Tools, LangChain/CrewAI/MCP Support

Released: May 1, 2026

🎊 Matimo v0.1.0 Stable — General Availability

After 14 alpha releases and extensive production testing, Matimo is now production-ready. This release represents the culmination of months of development, featuring a complete dual-SDK architecture, enterprise-grade security, and a rich ecosystem of 137+ production-tested tools.

📦 What’s New in v0.1.0

🧪 Bruno CLI Provider (NEW)

Complete API testing lifecycle support via Bruno integration:

7 New Tools:

Tool Purpose
bruno_create_collection Create new Bruno API collection
bruno_add_request Add HTTP request to collection (GET/POST/PUT/DELETE/PATCH)
bruno_get_collection_info Inspect collection structure and requests
bruno_list_collections Discover all Bruno collections in workspace
bruno_run_collection Execute entire collection with JSON reporter
bruno_run_request Run single named request from collection
bruno_import_openapi Bootstrap collection from OpenAPI 3.0 spec

Requirements: Bruno CLI (npm install -g @usebruno/cli)
Examples: pnpm bruno:complete (TS), uv run python bruno/complete_workflow.py (Python)

🔧 Meta-Tools Enhancement

2 New Meta-Tools for runtime tool discovery:

These join the existing 8 meta-tools (matimo_create_tool, matimo_validate_tool, matimo_approve_tool, matimo_reload_tools, matimo_list_user_tools, matimo_get_tool_status, matimo_create_skill, matimo_validate_skill, matimo_get_skill, matimo_list_skills) for complete self-maintenance capability.

⏱️ HITL (Human-in-the-Loop) Enhancements

New Features:

Example:

const matimo = await MatimoInstance.init('./tools', {
  hitlTimeoutMs: 120000, // 2 minutes
  onHitl: async (request) => {
    // Custom approval UI
    return { approved: true, reason: 'User reviewed' };
  }
});

🧹 Quality & Stability

🚀 Complete Feature Set (v0.1.0 Stable)

Core SDK (TypeScript + Python)

10 Provider Packages

Provider Tools Highlights
@matimo/slack / matimo-slack 16+ Messaging, channels, users, reactions
@matimo/github / matimo-github 10+ Issues, repos, users, releases
@matimo/gmail / matimo-gmail 5+ Send, read, search emails
@matimo/notion / matimo-notion 7+ Databases, pages, blocks
@matimo/hubspot / matimo-hubspot 50+ CRM, contacts, email campaigns
@matimo/mailchimp / matimo-mailchimp 8+ Lists, campaigns, members
@matimo/postgres / matimo-postgres 6+ Query, schema, transactions
@matimo/twilio / matimo-twilio 4+ SMS, calls, messaging
@matimo/bruno / matimo-bruno 7 API testing lifecycle (NEW)
@matimo/core / matimo-core 10+ Meta-tools, execute, edit, search

Framework Integrations

Documentation & Examples

📊 By the Numbers (v0.1.0)

Metric Value
Total Tools 137+
Provider Packages 10
Meta-Tools 10
Skills 14 built-in
Test Suites 98 (TypeScript) + 102 (Python)
Total Tests 2996
Test Coverage 95%+ (both SDKs)
Production Examples 40+
Supported Patterns 4 (Factory, Decorator, LangChain, CrewAI)
Supported Languages 2 (TypeScript, Python)
Python Versions 3.11, 3.12
Node Versions 18+, 20+, 22+

🔐 Security Hardening

All critical security patches applied:

  1. ✅ MCP Environment Isolation — No process.env seeding in MCP server
  2. ✅ Command Injection Prevention — Template placeholder validation
  3. ✅ Production Approval Secret — MATIMO_PRODUCTION_APPROVAL_SECRET enforcement
  4. ✅ Embedded Code Sandboxing — Function executor hardening
  5. ✅ Template Dollar Sign Fix — Prevent $&, $', $` special sequence injection

📦 Installation

TypeScript

npm install @matimo/core @matimo/slack @matimo/github @matimo/bruno
# or
pnpm add @matimo/core @matimo/slack

Python

pip install matimo-core[slack,github,bruno]
# or  
uv add matimo-core --extras slack --extras bruno

🎯 Migration from Alpha

From v0.1.0-alpha.14 → v0.1.0

Breaking Changes: None (100% backward compatible)
Deprecations: None
New Features: Bruno CLI, 2 meta-tools, HITL timeout/TTL

Simply update your package.json / pyproject.toml:

- "version": "0.1.0-alpha.14"
+ "version": "0.1.0"

All existing code, tool definitions, and configurations work as-is.

🙏 Acknowledgments

Special thanks to all contributors and alpha testers who helped make Matimo production-ready. This release represents the work of many hands and countless hours of testing, refinement, and community feedback.

v0.1.0-alpha.14-patch.1 — Bruno CLI Integration

Release: Bruno CLI provider package — first-class API testing lifecycle support for TypeScript and Python SDKs

Released: April 25, 2026

v0.1.0-alpha.14

Release: Python SDK Official Launch — Full-featured Python support for LangChain, CrewAI, and MCP with comprehensive examples, 657+ tests, 97.38% coverage, and enterprise-grade security hardening

Released: April 10, 2026

🐍 Python SDK — Official Launch

Core Features

Python SDK Release (matimo-core 0.1.0a14)

This is the official Python SDK, feature-parity with the TypeScript SDK plus Python-specific optimizations:

SDK Patterns (Identical to TypeScript)

# Factory Pattern (simplest)
from matimo import Matimo

matimo = await Matimo.init('./tools')
result = await matimo.execute('slack_send_message', {'channel': '#general', 'text': 'Hello'})
tools = matimo.list_tools()

# Decorator Pattern (class-based)
from matimo import tool, set_global_matimo_instance

set_global_matimo_instance(matimo)

class MyAgent:
    @tool('slack_send_message')
    async def send(self, channel: str, text: str): ...  # auto-executed

# LangChain Integration
from matimo import Matimo, convert_tools_to_langchain

matimo = await Matimo.init('./tools')
tools = convert_tools_to_langchain(matimo.list_tools(), matimo)
# Use with LangChain AgentExecutor, ReAct, etc.

# CrewAI Integration
from matimo import Matimo, convert_tools_to_crewai

matimo = await Matimo.init('./tools')
tools = convert_tools_to_crewai(matimo.list_tools(), matimo)
# Use with CrewAI Agent, Crew, etc.

🚀 Provider Tools (Python)

All 10 providers ship with full Python support:

Provider Tools Examples
Slack 16+ slack_send_message, slack_get_user, slack_list_channels, etc.
GitHub 10+ github_create_issue, github_list_repos, github_get_user, etc.
Gmail 5+ gmail_send_message, gmail_get_messages, etc.
Notion 7+ notion_create_database, notion_query_database, etc.
HubSpot 50+ hubspot_create_contact, hubspot_send_email, etc.
Mailchimp 8+ mailchimp_add_member, mailchimp_get_list, etc.
Postgres 6+ postgres_execute_query, postgres_get_schema, etc.
Twilio 4+ twilio_send_sms, twilio_make_call, etc.

Installation: pip install matimo-core[slack,github,gmail] (selective providers)

🤖 Framework Integrations

LangChain Integration (Python)

Full Feature Support:

Example:

from langchain.agents import create_react_agent, AgentExecutor
from langchain_openai import ChatOpenAI
from matimo import Matimo, convert_tools_to_langchain

matimo = await Matimo.init('./tools')
tools = convert_tools_to_langchain(matimo.list_tools(), matimo)

llm = ChatOpenAI(model='gpt-4')
agent = create_react_agent(llm, tools)
executor = AgentExecutor.from_agent_and_tools(agent=agent, tools=tools, verbose=True)

result = await executor.ainvoke({'input': 'Send a Slack message to #general saying hello'})

CrewAI Integration (Python)

Full Feature Support:

Example:

from crewai import Agent, Task, Crew
from langchain_openai import ChatOpenAI
from matimo import Matimo, convert_tools_to_crewai

matimo = await Matimo.init('./tools')
tools = convert_tools_to_crewai(matimo.list_tools(), matimo)

llm = ChatOpenAI(model='gpt-4')
agent = Agent(role='Slack Manager', goal='Send messages', tools=tools, llm=llm)
task = Task(description='Send hello to #general', agent=agent)
crew = Crew(agents=[agent], tasks=[task])

result = crew.kickoff()

MCP Server (Python)

Built-in Support:

Example:

from matimo import Matimo, create_mcp_server, MCPServerOptions

matimo = await Matimo.init('./tools')
server = await create_mcp_server(
    matimo,
    MCPServerOptions(name='my-agent', version='1.0.0')
)
await server.start()

📚 Python Examples (Production Patterns)

Native — Advanced Agent Demos (fully tested, exit 0)

These walkthroughs use real LangChain ReAct loops and verify each step programmatically. No mocks.

File Missions What it demonstrates
native/policy/policy_demo.py 11 Full policy lifecycle: risk classification, draft/deprecated/blocked tools, content validation, HITL approval, hot-reload atomicity, approval state tracking
native/skills/skills_demo.py 6 + Phase 4 Create/list/read/validate SKILL.md files via agent; get_skills_metadata() (L1), semantic_search_skills() (TF-IDF), build_relevant_skill_prompt() (L2)
native/meta_flow/meta_tools_integration.py 5 Full meta-tool lifecycle: matimo_create_tool → matimo_validate_tool → matimo_approve_tool → matimo_reload_tools → execute; policy-blocked tools (shell/file-reader)
native/logger_example.py 6 sections setup_logger(), JSON vs simple format, global singleton, SDK internal logger, level filtering, silent mode — no API key needed

Run them via:

cd python/
make policy-demo     # OPENAI_API_KEY required
make skills-demo     # OPENAI_API_KEY required
make meta-flow       # OPENAI_API_KEY required
make logger-example  # no key needed

Native — Factory & Decorator (no LLM required)

LangChain Integration (17 files)

CrewAI Integration (10 files)

Total Python examples: 58 files across 3 patterns and 8+ providers. All lint-clean (ruff), all end-to-end tested.

🔒 Security Hardening (6 Critical Patches)

Patch A: MCP Server Secret Isolation

Patch B: Command Injection Prevention

Patch C: Production Fail-Fast for Missing Approvals

Patch D: Embedded Code Sandboxing (Python)

🔐 Integration Layer Hardening

Case-Insensitive Secret Detection

Tool Name Sanitization for Pydantic

Comprehensive Auth Injection Testing

🚀 Performance Optimizations

CrewAI ThreadPoolExecutor Reuse

🔧 Build Quality & CI/CD

PEP 440 Version Compliance

Python Version Alignment

GitHub Actions Workflow Fixes

🧪 Test Coverage & Quality Metrics

Python Core (657 tests):

TypeScript Core (1,884 tests):

Total: 2,541 tests passing (TypeScript 1,884 + Python 657)

📖 Python Documentation

New Python-Specific Docs:

⚠️ Breaking Changes & Migration Guide

Aspect Old Behavior New Behavior Action
Python support Not available Official Python 3.11+ Update to Python 3.11+
CrewAI version Manual tool wiring convert_tools_to_crewai() Use conversion function
LangChain Python Not available Full support (langchain-core) Use conversion function
Secret detection Case-sensitive Case-insensitive No action (more secure)
Command injection Allowed edge cases Rejected at validation Review command definitions
Production approval Silent fallback Fail-fast Set APPROVAL_SECRET in prod
PEP 440 version 0.1.0-alpha.14 0.1.0a14 Automatic in PyPI

🎯 Cautions & Disclaimers

For AI Agents

For Developers

For Production

🚀 Upgrade Instructions

From alpha.13 (TypeScript users)

No breaking changes to TypeScript SDK; all security patches are backward-compatible.

For New Python Users

# Install core + specific providers
pip install matimo matimo-slack matimo-github

# With LangChain
pip install "matimo[langchain]" matimo-slack

# With CrewAI
pip install "matimo[crewai]" matimo-slack

# With everything
pip install "matimo[langchain,crewai]"

Verify Installation

import matimo
print(f"Matimo version: {matimo.__version__}")  # Should be 0.1.1.post1

# Quick test
from matimo import Matimo
matimo = await Matimo.init('./tools')
tools = matimo.list_tools()
print(f"Loaded {len(tools)} tools")

📊 Release Statistics

Metric Value
Total Tests 2,541 (1,884 TS + 657 Python)
Coverage 97.38% Python (exceeds 95% requirement)
Security Patches 6 (3 critical + 1 CodeQL + 2 optimization)
Python Modules 11 (core, 10 providers)
Python Examples 58 files (native, LangChain, CrewAI patterns)
TypeScript Examples 20+ (tools/, agents/, policy/, skills/)
Provider Tools 110+ across 8 providers (both SDKs)
Supported Python 3.11, 3.12
Framework Support LangChain, CrewAI, MCP (native), Decorator, Factory
Advanced Demos 4 (policy, skills, meta-tools, logger — fully tested)

v0.1.0-alpha.13

v0.1.0-alpha.13

Release: Skills System, Policy Engine, Meta-Tools Hardening — Complete agent autonomy layer with skill discovery, policy-driven tool creation, HITL quarantine, hot-reload safety, and security hardening

Released: March 22, 2026

🚀 Major Features

Skills System — First-Class Integration (@matimo/core)

Policy Engine (@matimo/core)

Full Policy Documentation

Hot-Reload Atomicity & Safety (@matimo/core)

Security Hardening (@matimo/core)

CLI Enhancements (@matimo/cli)

📚 Examples & Documentation

New Examples

New Documentation

🧪 Test Coverage

42 new test files added across unit, integration, and CLI suites:

📦 Packages

All packages bumped to v0.1.0-alpha.13:

⚠️ Breaking Changes

None. All new features are additive or opt-in.

🔗 Related

v0.1.0-alpha.12.1

Release: Per-Execution Credential Override — Multi-tenant credential injection, getRequiredCredentials() DX helper, package-level release workflow (Changesets), improved test coverage

Released: March 12, 2026

🚀 Features

Per-Execution Credential Override (@matimo/core)

getRequiredCredentials(toolName) DX Helper (@matimo/core)

New Example: Multi-Tenant Credentials (examples/tools/credentials/)

🧪 Test Coverage

📦 Packages

All packages bumped to v0.1.0-alpha.12.1:

⚠️ Breaking Changes

None. The options parameter on execute() is optional; all existing call sites continue to work unchanged.

v0.1.0-alpha.12

Release: First-Class MCP Support — Standalone server, pluggable secrets, Claude Desktop integration, comprehensive examples

Released: March 11, 2026

🚀 Major Features: MCP is Here

MCP Server Implementation (@matimo/core/mcp)

Pluggable Secret Resolution (SecretResolverChain)

CLI Commands: MCP First Class

New Examples: Complete MCP Integration

📚 Documentation

🔐 Security & Quality Improvements

CodeQL Fixes

CLI Robustness

Schema Fixes

📦 Packages

All packages bumped to v0.1.0-alpha.12:

🎯 Key Achievements

✅ Claude Desktop integration works out-of-the-box
✅ HTTP transport for remote/docker/network use cases
✅ Pluggable secrets (env, dotenv, vault, AWS)
✅ Zero configuration needed beyond YAML tool definitions
✅ Full test coverage for MCP flows
✅ Production-ready examples for all patterns
✅ Comprehensive troubleshooting documentation
✅ Security fixes from CodeQL review

⚠️ Breaking Changes

None. MCP is additive; existing SDK patterns (Factory, Decorator, LangChain) unchanged.

📝 Migration & Quick Start

Try MCP in 5 minutes:

# 1. Start MCP server (stdio — Claude Desktop compatible)
npx matimo mcp

# 2. In another terminal, generate Claude Desktop config
npx matimo mcp setup

# 3. Restart Claude Desktop, tools appear in Tools panel

For HTTP (remote/docker):

# Server
MATIMO_MCP_TOKEN=secret npx matimo mcp --transport http --port 3000

# Client (LangChain agent example)
cd examples/mcp
pnpm install
MATIMO_MCP_TOKEN=secret pnpm agent:http

v0.1.0-alpha.11

Release: Twilio SMS/MMS provider, Mailchimp email marketing provider, native Basic Auth support, enhanced HTTP executor form-encoding, comprehensive test coverage, production-ready examples.

Released: February 27, 2026

🚀 Features

New Providers (11 New Tools)

HTTP Executor Enhancements

Documentation & Examples

🛠 Fixes & Improvements

🔧 Technical Notes

⚠️ Breaking Changes

📝 Migration Notes

v0.1.0-alpha.10

Release: Notion tools provider, enhanced HTTP executor with structured parameters, and improved error handling

Released: February 21, 2026

🚀 Features

🛠 Fixes & Improvements

🔧 Technical Notes

⚠️ Breaking Changes

📝 Migration Notes

v0.1.0-alpha.9

Release: HubSpot provider, 50+ CRM tools, LLM-powered examples, approval enforcement, and full documentation

Released: February 19, 2026

🚀 Features

🛠 Fixes & Improvements

⚠️ Breaking Changes

📝 Migration Notes

v0.1.0-alpha.8

Release: focused on a unified approval system, logging, new GitHub tools, and workflow fixes

Released: February 18, 2026

🚀 Highlights

📦 Packages

🔧 Notable Changes

🐛 Fixes

v0.1.0-alpha.7.1

Patch: Discord release notifications + workflow improvements

Released: February 15, 2026

🔧 Updates

CI/CD Improvements

Security & Robustness

📊 Changes

🐛 Bug Fixes

v0.1.0-alpha.7

Postgres tools suite + SQL approval workflows: Execute database queries safely with interactive approval, LangChain integration, and comprehensive examples

Released: February 15, 2026

🚀 New Features

Postgres Package & Tools

SQL Approval Workflow System

📚 Examples & Documentation

4 Complete Postgres Examples

All 3 integration patterns (Factory, Decorator, LangChain) + SQL approval workflow:

  1. Factory Pattern — Direct tool execution with Matimo SDK
  2. Decorator Pattern — Class-based @tool() decorator usage
  3. LangChain Pattern — AI agent integration with table discovery and analysis
  4. Approval Workflow — Interactive SQL approval with automatic/manual modes

Comprehensive Documentation

CI/CD Enhancements

📦 Package Updates

🔧 Developer Experience

New APIs

Configuration

🐛 Fixes & Improvements

🔗 Related Documentation

⚠️ Breaking Changes

None. This is a purely additive release.

v0.1.0-alpha.6

Core tools architecture overhaul: function-based execution, unified SDK model, and comprehensive tool suite

Released: February 13, 2026

Security & Safety Improvements

Core Tools Architecture Overhaul

Execution Model Improvements

Testing & Examples

Schema & Tool Loading Improvements

Developer Experience

Quality & Reliability

Architecture Comparison

Before (alpha.5)

# Command-type execution (subprocess spawning)
execution:
  type: command
  command: 'tsx'
  args: ['packages/core/tools/read/read.ts', '{filePath}']

After (alpha.6)

# Function-type execution (direct calls)
execution:
  type: function
  code: './read.ts'

Benefits: Faster execution, no PATH dependencies, native error handling, simpler debugging

Tools Now Available

Core Utilities (6 tools)

Provider Integrations (21+ tools)

Examples

Execute Tool - All 3 Patterns

// Factory pattern
const matimo = await MatimoInstance.init('./tools');
const result = await matimo.execute('execute', {
  command: 'ls -la',
  cwd: '/tmp'
});

// Decorator pattern
@tool('execute')
async runCommand(command: string) { }

// LangChain pattern
const tools = matimo.listTools()
  .map(t => ({ type: 'function', function: {...} }));

Read Tool

const result = await matimo.execute('read', {
  filePath: './src/index.ts',
  startLine: 10,
  endLine: 50,
});

Edit Tool

const result = await matimo.execute('edit', {
  filePath: './config.json',
  newContent: '{"updated": true}',
  createBackup: true,
});

Search Tool

const result = await matimo.execute('search', {
  pattern: 'function execute',
  directoryPattern: './src/**/*.ts',
  outputLines: true,
});

Web Tool

const result = await matimo.execute('web', {
  url: 'https://example.com',
  method: 'GET',
});

Migration from Alpha.5

If you were using core tools:

Before (command-type with tsx):

// Tools required tsx in PATH
const result = await matimo.execute('read', {...});

After (function-type, no dependencies):

// Same API, better performance, no PATH dependencies
const result = await matimo.execute('read', {...});

API remains the same — no code changes needed! Just update Matimo version.

Testing & Quality

Known Issues & Limitations

This is an alpha release. Not recommended for production without thorough testing.

Installation

npm install matimo@0.1.0-alpha.6
pnpm add matimo@0.1.0-alpha.6

Documentation

Contributing

Contributing Guide Report Issues

v0.1.0-alpha.5

Readme addition to core, slack and gmail packages and custom domain setup for github pages (docs).

Released: February 11, 2026

What’s New

Notes

v0.1.0-alpha.4

Packaging restructure, Matimo CLI, independent tools package publishing, and docs

Released: February 10, 2026

What’s New

Notes

v0.1.0-alpha.3

Slack integration suite, standardized error handling, improved test coverage, and comprehensive documentation

Released: February 5, 2026

What’s New

Slack Integration Suite

Error Handling & Quality

Testing Improvements

Examples & Documentation

Package Improvements

What’s Improved from Alpha.2

Installation

npm install matimo@0.1.0-alpha.3
pnpm add matimo@0.1.0-alpha.3

Quick Start - Three Integration Patterns

1. Factory Pattern (Direct SDK Usage)

const matimo = await MatimoInstance.init('./tools');
const result = await matimo.execute('slack-send-message', {
  channel: '#general',
  message: 'Hello from Matimo!',
});

2. Decorator Pattern (Class-Based)

@tool('slack-send-message')
async sendMessage(channel: string, message: string) {
  // Auto-executed via Matimo
}

3. LangChain Integration (AI Agents)

const tools = matimo.listTools()
  .map(t => ({
    type: 'function',
    function: { name: t.name, description: t.description, ... }
  }));
const response = await llm.invoke(messages, { tools });

Tools Included

Documentation

Known Limitations

This is an alpha release. Not recommended for production without thorough testing.

See Roadmap for future features (REST API, MCP server, Python SDK, rate limiting).

Contributing

Contributing Guide Report Issues

v0.1.0-alpha.2

Improved alpha.1 release - Better npm workflow, fixed exports, accurate feature descriptions

Released: February 4, 2026

What’s Improved

Release & Distribution

Package & Exports

v0.1.0-alpha.1

First alpha release - Core OAuth2, tool execution, and SDK patterns

Released: February 3, 2026

What’s New

OAuth2 Multi-Provider Support

Tool System

SDK Patterns

Tools Included

Installation

npm install matimo@0.1.0-alpha.1
pnpm add matimo@0.1.0-alpha.1

Quick Start

import { matimo } from 'matimo';

const m = await matimo.init('./tools');
const result = await m.execute('calculator', {
  operation: 'add',
  a: 5,
  b: 3,
});

Documentation

Known Limitations

This is an alpha release. Not recommended for production without thorough testing.

See Roadmap for future features.

Contributing

Contributing Guide Report Issues