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

v0.1.8 - Governance Gap Closures: Default Policy Engine, Approve→Reload Lifecycle & Audit Events 🛡️

Release: Closes the gap between what Matimo’s docs claim about governance (“every tool call passes through a policy engine”, “full audit trail”) and what a zero-config instance actually enforced - MatimoInstance.init() now always gets a real DefaultPolicyEngine, the matimo_approve_tool → reloadTools() lifecycle no longer trusts stale hashes, SSRF targets are re-checked at the fully-resolved URL immediately before a request fires, and the simple per-tool requires_approval flag now emits real audit events. Plus a large wave of Windows/cross-platform fixes and a full documentation accuracy audit.

Released: August 30, 2026 Scope: typescript/ workspace - all 13 packages (core, cli, bruno, slack, gmail, github, hubspot, notion, mailchimp, microsoft, postgres, twilio, composio) bumped to 0.1.8 in lockstep. Severity: 🟠 Important - closes real governance gaps in the default (zero-config) code path; no breaking API changes.

🛡️ Governance: Default Policy Engine & Approve→Reload Lifecycle

A six-finding pass on the self-extension workflow (matimo_create_tool → matimo_approve_tool → matimo_reload_tools) and the zero-config default:

  1. Policy engine is no longer optional. MatimoInstance.init() now always constructs a DefaultPolicyEngine() when no policy option is given, matching Python’s existing behavior. Previously a zero-config instance had #policy as null and every governance check was silently skipped.
  2. Approve → reload hash-timing bug fixed. matimo_approve_tool computed its approval hash from the tool’s pre-mutation content, then overwrote the file afterward - so isApproved() could never validate against the tool’s actual post-approval on-disk state, and the SDK’s own documented self-extension workflow never completed end-to-end. The hash is now computed after the status: approved write. reloadTools() also now consults the approval manifest before gating an untrusted tool: a legitimately-approved tool uses a new, narrower canReload() (skips only “new proposal” rules), while anything never legitimately approved - including a hand-edited status: approved that bypassed matimo_approve_tool - still falls back to canCreate().
  3. SSRF re-checked at execution time. HttpExecutor now re-validates the fully-resolved URL against SSRF targets immediately before the HTTP request fires, closing the gap where creation-time validation only ever saw {placeholder}-blanked URLs.
  4. Path traversal closed on 3 more meta-tools. matimo_get_tool and matimo_get_tool_status now sanitize their name parameter against the same pattern matimo_create_tool already used; matimo_approve_tool picked this up as part of the hash-timing rewrite.
  5. Risk can only go up. A tool’s self-declared risk: field can now only raise the automatically computed risk level, never lower it.
  6. Production-environment matching fixed. The production gate now does a case-insensitive substring match ('prod' in environment.toLowerCase()) instead of an exact === 'prod' comparison - matching Python’s existing behavior and Matimo’s own docs/examples, which use 'production'.

Also adds reloadSkills(), mirroring reloadTools()’s clear/re-walk/re-register shape, plus a new skills:reloaded event.

✨ Enhancement: audit events for the simple requires_approval flow

onEvent previously only fired from DefaultPolicyEngine’s create/quarantine paths - so the plain per-tool requires_approval: true YAML flag (the approval mechanism active by default, with no policy/policyFile/policyConfig configured) produced zero audit events, contradicting the README’s “full audit trail via structured events” claim. New tool:approval_granted / tool:approval_denied events now fire around ApprovalHandler.requestApproval() regardless of whether a full PolicyEngine is configured.

🐛 Fixes

🪟 Windows / cross-platform fixes

🧹 Example fixes

📚 Documentation

A full accuracy audit against current code, across docs/, package READMEs, and docs/ROADMAP.md:

🌐 Website / SEO

Fixed a broken og:image/JSON-LD image path, a duplicate JSON-LD key that silently dropped the npm install link, a stale softwareVersion, an over-length meta description, a duplicated robots.txt rule block, and a same-host sitemap violation (docs.matimo.dev URLs listed inside matimo.dev’s own sitemap) on the landing page.

🔐 Security note (flagged, not fixed in this release)

pnpm audit reports 32 vulnerabilities (2 low / 11 moderate / 19 high), all transitive via @modelcontextprotocol/sdk’s dependency chain (express → body-parser, hono). This needs a deliberate SDK-dependency-bump task - tracked separately, not absorbed into this release.

📦 Version Bumps

Package Previous New Type
matimo (root, typescript/) 0.1.7 0.1.8 Patch
@matimo/core 0.1.7 0.1.8 Patch
@matimo/cli 0.1.7 0.1.8 Patch
@matimo/bruno 0.1.7 0.1.8 Patch
@matimo/slack 0.1.7 0.1.8 Patch
@matimo/gmail 0.1.7 0.1.8 Patch
@matimo/github 0.1.7 0.1.8 Patch
@matimo/hubspot 0.1.7 0.1.8 Patch
@matimo/notion 0.1.7 0.1.8 Patch
@matimo/mailchimp 0.1.7 0.1.8 Patch
@matimo/microsoft 0.1.7 0.1.8 Patch
@matimo/postgres 0.1.7 0.1.8 Patch
@matimo/twilio 0.1.7 0.1.8 Patch
@matimo/composio 0.1.7 0.1.8 Patch

Note on semver strictness: this batch includes one genuine feat: commit (audit events, above). A strict reading of this project’s own conventional-commits rule (feat: → minor) would argue for 0.2.0 rather than 0.1.8; this release follows established precedent (the v0.1.6→v0.1.7 jump also shipped a feat commit and was still released as a patch-level bump) and the branch name (release/v0.1.8). Flagged here for visibility rather than silently decided.

🧪 Verification

Python v0.1.3 - Governance Parity & Cross-Platform Fixes 🐍

Release: Brings Python to parity with the TypeScript v0.1.8 governance fixes above - default policy engine, approve→reload lifecycle, execution-time SSRF re-check, path-traversal sanitization on 3 meta-tools - plus a Windows/cross-platform fix to skill-resource containment checking and a fix that had provider packages silently failing to install in the workspace.

Released: August 30, 2026 Scope: python/ workspace - all 13 packages (matimo-core, matimo-cli, matimo meta-package, matimo-bruno, matimo-slack, matimo-gmail, matimo-github, matimo-hubspot, matimo-notion, matimo-mailchimp, matimo-microsoft, matimo-postgres, matimo-twilio) bumped to 0.1.3 in lockstep. Severity: 🟠 Important - closes real governance gaps in the default code path; no breaking API changes.

🛡️ Governance: Default Policy Engine & Approve→Reload Lifecycle (parity with TS)

Mirrors the TypeScript fixes above, with a few points where the Python side had actually diverged further:

🐛 Fix: cross-platform skill-resource containment check

The skill-resource containment check hardcoded a forward-slash separator (str(resolved).startswith(str(skill_dir_resolved) + "/")), which never matches Path.resolve()’s backslash-separated output on Windows - every resource read was rejected as “escaping” the skill directory even when it wasn’t. Replaced with Path.is_relative_to(), the correct separator-agnostic check.

🐛 Fix: provider packages weren’t installed by default

Root pyproject.toml listed all 10 provider packages under [tool.uv.workspace].members and [tool.uv.sources] but never in [project].dependencies, so uv sync --all-extras --dev never actually installed them - causing 74 test failures and 2 collection errors from ModuleNotFoundError, concentrated in bruno and microsoft. Now matches the TypeScript side’s “always installed” workspace behavior.

🧹 Example fixes

Execute-tool examples: the Python execute tool spawns commands directly via asyncio.create_subprocess_exec() with no shell involved, so shell builtins and pipes were never available regardless of platform - switched the examples to git subcommands (real installed executables everywhere), and fixed two decorator-example methods that sent no command at all because they declared no parameters. Verified by running all four examples end-to-end on Windows.

📚 Documentation

Same repo-wide accuracy audit as the TypeScript release above: python/README.md’s quickstart called Matimo.init(providers=[...]), a parameter that doesn’t exist, and its per-provider tool counts were stale and missing bruno/microsoft entirely (recounted directly from definition.yaml files on disk); HubSpot’s docs pointed at HUBSPOT_ACCESS_TOKEN when tools actually read MATIMO_HUBSPOT_API_KEY; Postgres had a wrong tool name, wrong env var prefixes, and a false requires_approval claim; GitHub/Gmail quick-starts were missing the provider name prefix on tool calls; the CLI README documented 6 flags/features that don’t exist; AGENTS.md/llms.txt added alongside the TypeScript ones.

⬆️ Dependency bumps (Dependabot, routine)

pypdf 6.14.2→6.15.0, cryptography (examples/mcp), aiohttp 3.14.1→3.14.3 (both python/ and python/examples/mcp), pillow 12.2.0→12.3.0, mcp →1.28.1 (both python/ and python/examples/mcp), litellm 1.72.0→1.84.0, json-repair 0.25.2→0.60.1.

📦 Version Bumps

Package Previous New Type
matimo (meta-package) 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-slack 0.1.2 0.1.3 Patch
matimo-gmail 0.1.2 0.1.3 Patch
matimo-github 0.1.2 0.1.3 Patch
matimo-hubspot 0.1.2 0.1.3 Patch
matimo-notion 0.1.2 0.1.3 Patch
matimo-mailchimp 0.1.2 0.1.3 Patch
matimo-microsoft 0.1.2 0.1.3 Patch
matimo-postgres 0.1.2 0.1.3 Patch
matimo-twilio 0.1.2 0.1.3 Patch

No feat: commits touch python/ in this batch (the audit-events feature above is TS-only; @matimo/composio has no Python counterpart per the known TS/Python parity gap) - this is an unambiguous patch bump.

🧪 Verification

Known non-blocking issue (pre-existing, not introduced by this release): mypy strict typecheck on packages/core/src currently reports 127 errors across 25 files, traced via git blame to code from April 5, 2026 - well before python/v0.1.2. This repo’s own CI already runs mypy non-blocking (mypy packages/ || true in .github/workflows/ci.yml and test-python.yml, with an explicit “union type refinement work in progress” comment), so it was not treated as a release blocker here either. Flagged for visibility.

v0.1.7 — Composio Google Workspace Expansion: Gmail, Sheets, Docs, Forms, Meet 📇

Release: Five new Composio-backed Google Workspace toolkits (Gmail, Sheets, Docs, Forms, Meet) adding 107 governed tools, plus explicit BYOK compliance documentation for the Composio dependency, two small fixes, and a flaky-test timeout fix.

Released: August 11, 2026 Scope: typescript/ workspace — all 13 packages (core, cli, bruno, slack, gmail, github, hubspot, notion, mailchimp, microsoft, postgres, twilio, composio) bumped to 0.1.7 in lockstep. Python untouched this release. Severity: 🟢 Additive — new tools and documentation only, no breaking changes to existing package APIs

✨ Composio: 5 new Google Workspace toolkits

@matimo/composio’s generated catalog grows from 342 → 449 tools across 9 → 14 toolkits: Gmail (23), Google Sheets (36), Google Docs (32), Google Forms (7), and Google Meet (9). Same governed-access model as every other composio_* tool — bring-your-own COMPOSIO_API_KEY + composio_connected_account_id, risk-classified, policy-gated.

🧪 Gmail: example coverage

The new Gmail toolkit is exercised across all four example patterns (factory, decorator, LangChain, HITL-approval).

📚 Composio: BYOK & third-party notices

Documented @matimo/composio’s bring-your-own-key credential model explicitly: a non-affiliation disclaimer and links to Composio’s Terms of Service and Privacy Policy were added to the package README and docs/COMPOSIO.md. Added THIRD_PARTY_NOTICES.md, listing every provider Matimo can connect to, its credential env var, and a link to that provider’s own terms. CONTRIBUTING.md and SECURITY.md now mandate the BYOK pattern for all future third-party connectors, not just Composio.

🐛 Fixes

v0.1.6 — Document & Web Tooling: web_scraper, convert_to_file, extract_from_file 🛠️

Release: Three new core tools for pulling content into an agent’s context and turning agent output into shippable files, plus expression-mode calculator, a Gmail attachment tool, a Bruno bug fix, and a round of dependency security patches.

Released: July 15, 2026 Scope: typescript/ workspace — all 13 packages (core, cli, bruno, slack, gmail, github, hubspot, notion, mailchimp, microsoft, postgres, twilio, composio) bumped to 0.1.6 in lockstep. Corresponding Python changes land in Python v0.1.2, immediately below. Severity: 🟢 Additive — three new tools, one new tool parameter mode, one bug fix, no breaking changes to existing package APIs

✨ New Core Tool: web_scraper

Crawls a website starting from a given URL and extracts the main readable content of every page discovered within the same domain (child/sibling pages reachable via same-domain links), bounded by maxPages/maxDepth. No headless browser — fetches HTML directly and extracts readable content via @mozilla/readability + jsdom (TypeScript) / readability-lxml + markdownify (Python).

✨ New Core Tool: convert_to_file

Converts structured content between JSON, CSV, Markdown, and plain text into a target file format: JSON↔CSV round-tripping, Markdown→PDF, Markdown→DOCX, plain text→DOCX/TXT. Markdown is parsed into headings/paragraphs/lists before being re-rendered into the target format, rather than dumped as raw text. TypeScript: marked + pdfkit + docx. Python: mistune + reportlab + python-docx.

✨ New Core Tool: extract_from_file

Extracts text content from a local or remote file — PDF (text extraction), DOCX (raw text extraction), plain text/CSV. Format is auto-detected from the file extension and magic bytes unless explicitly specified. TypeScript: pdf-parse + mammoth. Python: pypdf + python-docx.

✨ Calculator: expression mode

calculator now supports two mutually exclusive modes: the existing binary/unary operation + a/b mode, and a new expression string mode with full operator precedence, parentheses, and the constants pi/e (e.g. "sqrt(16) + 2^3 - sin(pi/2)"). An optional precision rounds the final result. Expressions are evaluated in a sandboxed parser — mathjs in TypeScript, simpleeval in Python — never raw eval()/Function().

✨ Gmail: get-attachment tool

Fetches a Gmail message attachment by ID, returning its size and base64url-encoded raw data.

🐛 Fix: Bruno tools silently discarded subprocess errors

bruno_run_collection and bruno_run_request always returned an empty errors array on subprocess failure, discarding bru’s stderr output — making failures undebuggable. Both now capture stderr into errors when the process exits non-zero. bruno_run_request also concatenated stdout/stderr with a stray leading newline when stdout was empty; now joins only the parts that are present.

🔐 Security: dependency bumps

📚 Documentation

🧪 Verification

Python v0.1.2 — Document Tooling Parity, Calculator Expressions & Bruno Fix 🐍

Release: Python-side parity with the TypeScript v0.1.6 release above — same three new core tools, same calculator expression mode, same Bruno fix.

Released: July 15, 2026 Scope: python/ workspace — all 13 packages (matimo-core, matimo-cli, matimo meta-package, matimo-bruno, matimo-slack, matimo-gmail, matimo-github, matimo-hubspot, matimo-notion, matimo-mailchimp, matimo-microsoft, matimo-postgres, matimo-twilio) bumped to 0.1.2 in lockstep, matching the versioning strategy TypeScript already uses. Previously, only the matimo meta-package (last at 0.1.1.post1) and matimo-core (last at 0.1.0) had diverged; this release re-synchronizes every package. Severity: 🟢 Additive — no breaking changes; matimo-core’s dependency bound (>=0.1.0,<0.2.0) on every provider package already covers 0.1.2, so no constraint changes were needed

✨ New matimo-core tools: web_scraper, convert_to_file, extract_from_file

Same behavior as the TypeScript versions (see v0.1.6 above). New dependencies added to matimo-core: pypdf, python-docx, mistune, reportlab, readability-lxml, markdownify, lxml-html-clean.

✨ Calculator: expression mode

Same expression parameter mode as TypeScript, evaluated via simpleeval (never raw eval()). New dependency: simpleeval.

✨ Gmail: get-attachment tool

Python executor added alongside the TypeScript one.

🐛 Fix: Bruno tools silently discarded subprocess errors

Same root cause and fix as the TypeScript side — bruno_run_collection/bruno_run_request now populate errors from stderr on non-zero exit, and bruno_run_request no longer prepends a stray newline when stdout is empty. Also fixed a test assertion in test_bruno_tools.py that expected collection.name to be None when no bruno.json is present — the tool correctly falls back to the directory name, matching the TypeScript implementation.

🧪 Verification

v0.1.5 — @matimo/composio: Governed Access to 342 Composio Tools 🔌

Release: Introduces @matimo/composio — a policy-governed, risk-classified wrapper around Composio’s integration catalog. Agents now get governed, auditable, human-approvable access to Jira, Google Workspace, Microsoft 365, Asana, Linear, and more without losing Matimo’s policy engine.

Released: June 21, 2026 Scope: typescript/ workspace — all 13 packages (core, cli, bruno, slack, gmail, github, hubspot, notion, mailchimp, microsoft, postgres, twilio, composio) bumped to 0.1.5 in lockstep Severity: 🟢 Additive — new package + dependency maintenance, no breaking changes to existing package APIs

⬆️ 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