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)

Agent Skills Catalog — 6 built-in SKILL.md files shipped with @matimo/core for agent self-education
- tool-creation — matimo_create_tool, matimo_validate_tool, matimo_approve_tool workflow
- meta-tools-lifecycle — Full lifecycle management (create, validate, approve, reload, list)
- policy-validation — Risk classification, approval tiers, policy configuration
- tool-discovery — Finding and learning about existing tools
- skill-creator — How to create new SKILL.md files for use in agents
- skills-catalog — How to use and leverage the skills ecosystem
semanticSearchSkills(query) — TF-IDF (Term Frequency - Inverse Document Frequency embedding)-based semantic search across all SKILL.md files; ranked results with relevance scores
- TF-IDF implementation details
getSkillSections(skillName) — Returns section inventory with token estimates for progressive disclosure
getSkillContent(skillName, options?) — Load full or selective sections of a skill (token-efficient context loading)
getSkillsMetadata(matimo) — Non-MCP LangChain helper: returns Array<{ name, description }> only (Level 1, no file I/O, always token-safe)
buildRelevantSkillPrompt(matimo, query, options?) — Non-MCP LangChain helper: runs TF-IDF cosine similarity ranking and loads only the top-K relevant skills above a minimum score into a ready-to-inject system prompt block (Level 2, lazy). Both helpers exported from matimo — see LangChain integration guide
Agent meta-tools — 10 meta-tools callable by LangChain agents and MCP clients:
- Skill meta-tools: matimo_list_skills, matimo_get_skill, matimo_create_skill, matimo_validate_skill
- Tool lifecycle meta-tools: matimo_create_tool, matimo_validate_tool, matimo_approve_tool, matimo_reload_tools, matimo_list_user_tools, matimo_get_tool_status
- See META_TOOLS.md for full reference
Provider skill bundles — Each provider package ships a consolidated SKILL.md documenting its complete tool ecosystem (Slack, GitHub, Gmail, HubSpot, Mailchimp, Notion, Postgres, Twilio)
MCP resource exposure — Skills auto-registered as skills://{name} resources on the MCP server; Claude Desktop and Cursor can read them via the Resources protocol without tool calls; hot-reloads on reloadTools()

Policy Engine (@matimo/core)

Full Policy Documentation

Policy-as-YAML loader — loadPolicyFromFile(path) + policyFile option in MatimoInstance.init()
Policy tier API — getTierForTool(tool, config): PolicyTier returning 'auto' | 'approval-required' | 'blocked'
Approval state tracking — approvalState: 'auto-approved' | 'pending' | 'approved' | 'rejected' in CreateResult
Pending tools inventory — getPendingTools(): string[] in approval manifest for agent status queries
Tool status meta-tool — matimo_get_tool_status returns { name, status, riskLevel, approvalState, approvedAt?, approvedBy? }
Human-readable validation — matimo_validate_tool returns SchemaError[] with validOptions? per field (not raw Zod output)
Content validator — content-validator.ts scans agent-written tool YAML for blocked patterns (SSRF, secrets in plain text, unsafe command templates) before the tool reaches the registry
Integrity tracker — integrity-tracker.ts records a hash of each approved tool file; detects file tampering between restarts
Policy events — events.ts emits typed lifecycle events (tool:created, tool:approved, tool:rejected, tool:quarantined) for external monitoring hooks
HITL quarantine — Tools that fail content validation during a policy-restricted session are written to a quarantine directory rather than discarded; human reviewer can inspect, amend, and re-submit via matimo review

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

Atomic reload — reloadTools() snapshots registry, restores on mid-load error
Rollback signal — ReloadResult { success, reloadedCount, rolledBack } tells agents whether state was preserved
MCP auto-trigger — MCP server emits tools/list_changed + resources/list_changed notifications on successful reload

Security Hardening (@matimo/core)

20 security vulnerabilities resolved via pnpm overrides and direct fixes:
- ReDoS prevention — HEADING_REGEX hardened against catastrophic backtracking in skill section parsing
- Sensitive data logging — Secrets never logged or exposed in error messages or stack traces
- Dependency audit — Comprehensive override strategy for transitive vulnerabilities
Regex safety — All regex patterns reviewed and hardened
Logging guardrails — Credentials and sensitive parameters redacted from all logs

CLI Enhancements (@matimo/cli)

matimo doctor — Diagnoses environment in one command:
- Node.js ≥18 check
- @matimo/* package scan
- Environment variable audit per tool
- YAML validation with field-level messages
matimo review — Bridge for approval workflows:
- matimo review list — Show pending and quarantined tools awaiting approval
- matimo review approve <tool-name> — Approve a pending tool (updates approval manifest + tool status)
- matimo review reject <tool-name> — Reject a pending tool

📚 Examples & Documentation

New Examples

examples/tools/policy/policy-demo.ts — LangChain agent demonstrating the full policy-aware tool creation workflow (create → validate → quarantine → review → approve → execute)
examples/tools/skills/skills-demo.ts — Multi-phase demo: agent skill missions (create, list, read, validate), Phase 4 direct TF-IDF ranking via semanticSearchSkills() with per-skill scores, and non-MCP progressive disclosure via getSkillsMetadata() + buildRelevantSkillPrompt()
examples/tools/meta-flow/meta-tools-integration.ts — Full lifecycle: create tool, validate, approve, reload, list via meta-tools; includes policy agent and skills agent in one flow
examples/tools/agents/langchain-skills-policy-agent.ts — Production-pattern LangChain agent combining skills discovery (Level 1 + Level 2) with policy-aware tool creation in a single mission-based ReAct loop
examples/tools/validate-implementation.ts — SDK validation script that verifies all meta-tools, skill operations, and policy flows are wired correctly end-to-end

New Documentation

docs/api-reference/META_TOOLS.md — Complete reference for all 10 meta-tools (parameters, return shapes, examples, approval requirements)
docs/api-reference/POLICY_AND_LIFECYCLE.md — Policy engine deep-dive: tier system, YAML config, HITL quarantine flow, approval manifest schema, integrity tracker
docs/skills/TFIDF_SEMANTIC_SEARCH.md — TF-IDF implementation details: tokenization, IDF computation, cosine similarity, embedding cache, custom provider interface
docs/skills/SKILLS.md — Complete Skills System guide: SKILL.md format, progressive disclosure levels, MCP resource exposure, LangChain non-MCP helpers, semantic search API
docs/framework-integrations/LANGCHAIN.md — Added Skills Integration (Non-MCP) section: getSkillsMetadata + buildRelevantSkillPrompt API reference with full options and code patterns
docs/ROADMAP.md — Updated with alpha.14 focus (agent-callable TF-IDF, matimo_search_skills, dynamic tool filtering)
docs/tool-development/TOOL_SPECIFICATION.md — execution.type: function fully documented with trust model

🧪 Test Coverage

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

Meta-tools: Unit tests for all 10 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_get_skill, matimo_list_skills, matimo_validate_skill)
Policy engine: Unit tests for approval-manifest, content-validator, default-policy, hitl-quarantine, integrity-tracker, risk-classifier, policy loader and parser
Skills system: TF-IDF embedding, section parser, skill-loader, skill-registry (core + semantic), langchain-integration helpers (getSkillsMetadata, buildRelevantSkillPrompt)
Integration: Hot-reload atomicity, HITL quarantine paths, matimo-instance-hitl-paths, policy integration end-to-end
CLI: doctor command, review approve/reject/list commands
Full suite: 1,884 tests passing across 96 test suites

📦 Packages

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

@matimo/core — Skills, policy engine, 10 meta-tools, HITL quarantine, security fixes, LangChain helpers
@matimo/cli — doctor command, review command, enhanced help
@matimo/slack, @matimo/github, @matimo/gmail, @matimo/hubspot, @matimo/mailchimp, @matimo/notion, @matimo/postgres, @matimo/twilio — Version sync, provider SKILL.md bundles in each

⚠️ Breaking Changes

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

Previous: v0.1.0-alpha.12.1
Next: v0.1.0-alpha.14

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)

ExecuteOptions.credentials — Pass Record<string, string> per execute() call; credentials are scoped to that execution and never written to process.env
Priority lookup chain: credentials[key] → credentials[MATIMO_key] → process.env[MATIMO_key] → process.env[key]
All executor types updated: HttpExecutor, CommandExecutor, FunctionExecutor all accept and forward per-call credentials
Fully backward compatible: existing code without options is unaffected

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

Returns the exact credential key names a tool expects (string[])
Scans {PLACEHOLDER} patterns in headers, URL, body, and query_params for auth-pattern names
Also includes username_env / password_env from authentication.type: basic config
Throws MatimoError(TOOL_NOT_FOUND) for unknown tool names

Enables multi-tenant credential manifest pattern:

const keys = matimo.getRequiredCredentials('slack-send-message');
// → ['SLACK_BOT_TOKEN']
const credentials = Object.fromEntries(keys.map(k => [k, tenant.secrets[k]]));
await matimo.execute('slack-send-message', params, { credentials });

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

Runnable demo showing per-tenant credential isolation with Promise.all parallel execution
Verifies process.env immutability and env-var fallback behaviour
Credential key reference table for all Slack tools
Script: pnpm credentials:example

🧪 Test Coverage

26 new tests in credentials-override.test.ts covering all executors, credential priority, getRequiredCredentials(), and process.env immutability
8 new branch-coverage tests in matimo-instance.test.ts targeting previously uncovered paths:
- params.command scan for command-type tools
- params.sql destructive-keyword scan
- MATIMO_APPROVAL_SCAN_ALL_PARAMS=true path
- Approval callback invocation
- Basic-auth username_env/password_env in getRequiredCredentials()
- scanObjectForParams non-object early return & circular reference guard
- getExecutor unsupported-type throw
matimo-instance.ts statements and lines: 100% (up from 88.81% / 89.74%)
Full suite: 1298+ tests passing

📦 Packages

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

@matimo/core — ExecuteOptions, getRequiredCredentials(), new tests
@matimo/cli — Version sync
@matimo/slack, @matimo/github, @matimo/gmail, @matimo/hubspot, @matimo/mailchimp, @matimo/notion, @matimo/postgres, @matimo/twilio — Version sync

⚠️ 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)

Dual-transport support:
- Stdio transport — Lightweight, no networking, perfect for Claude Desktop and local agents
- Streamable HTTP transport — Remote deployment ready, bearer token auth, reconnect logic
Tool discovery & execution — MCP protocol compliant; Claude instantly sees all loaded tools
Session management — Handles MCP client lifecycle, graceful shutdown with active connection draining
Zero configuration — Works with default YAML tool definitions; no MCP-specific schema needed

Pluggable Secret Resolution (SecretResolverChain)

Multiple backends supported:
- env — Load from environment variables (fastest, default)
- dotenv — Load from .env file (development friendly)
- vault — HashiCorp Vault integration (enterprise secrets)
- aws — AWS Secrets Manager integration (cloud-native)
Automatic injection — Tool parameters matching auth patterns (token, key, secret, etc.) auto-resolved server-side
Chain resolution — Try resolvers in order; fall back gracefully if missing

CLI Commands: MCP First Class

matimo mcp — Start MCP server
- --transport stdio — Default, no networking
- --transport http --port 3000 — Remote, auth-ready
- --tools slack,gmail — Tool allowlist/denylist
- --secrets env,dotenv,vault — Enable secret backends
matimo mcp setup — Generate Claude Desktop config
- Auto-discovers Matimo bin path
- Generates valid claude_desktop_config.json
- Writes to ~/.config/Claude/claude_desktop_config.json (macOS/Linux)

New Examples: Complete MCP Integration

examples/mcp/ — Full-featured MCP demo
- agent-stdio.ts — Claude Desktop integration via stdio
- agent-http.ts — LangChain agent via HTTP transport
- agent.ts — Unified agent supporting both transports
- README.md — Step-by-step setup with real Slack tools
- .env.example — All environment variables documented
- package.json scripts — pnpm agent:stdio, pnpm agent:http, pnpm mcp:start:http

📚 Documentation

docs/MCP.md — Complete MCP architecture guide
- Endpoints reference (GET /mcp for health, SSE for streams)
- MCP spec compliance notes
- TLS setup (mkcert recommended for local HTTPS)
- Troubleshooting guide
examples/mcp/README.md — Quick start (5 minutes to Langchain Agent with Slack integration via mcp)
- Prerequisites (Node, npm, OpenAI key, Slack token)
- Quick Start section with 2 patterns (stdio, HTTP)
- Environment variable reference
- Troubleshooting (connection, token, tools)

🔐 Security & Quality Improvements

CodeQL Fixes

Polynomial regex (ReDoS) — Fixed /\{([^}]+)\}/g → /\{(\w+)\}/g in tool-converter.ts
TLS bypass removed — Deleted NODE_TLS_REJECT_UNAUTHORIZED = '0' from examples; plain HTTP default for localhost
HTTP server shutdown — Added closeIdleConnections() + closeAllConnections() to drain active SSE streams before closing

CLI Robustness

Flag validation — All value-consuming flags now guard against missing args with clear error messages
Auto-execution detection — Fixed to handle different tsx versions’ argv-shifting behavior

Schema Fixes

Zod optional-before-default — Fixed parameter-to-Zod conversion so defaults apply correctly to non-required params

📦 Packages

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

@matimo/core — New mcp exports; schema/security fixes
matimo-cli — New mcp and mcp setup commands; updated help
matimo-mcp-examples — New project with full MCP integration

🎯 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)

Twilio Provider (packages/twilio) — 4 SMS/MMS Tools
- twilio-send-sms — Send SMS to E.164 formatted phone numbers with message content and optional callbacks
- twilio-send-mms — Send MMS with media URLs to recipients
- twilio-get-message — Retrieve message status and details by SID
- twilio-list-messages — List messages with filtering (to/from phone, date, pagination)
- E.164 phone number format validation and handling
- Trial account support (50 messages/day limit)
- Full Twilio Programmable Messaging API integration
Mailchimp Provider (packages/mailchimp) — 7 Email Marketing Tools
- mailchimp-get-lists — Retrieve email lists from account
- mailchimp-add-list-member — Add subscribers to lists (with merge fields)
- mailchimp-update-list-member — Update subscriber information (email, name, status)
- mailchimp-get-list-members — Query list members with pagination
- mailchimp-remove-list-member — Remove subscribers from lists
- mailchimp-create-campaign — Create new email campaigns with templates
- mailchimp-send-campaign — Send campaigns to lists with content
- Full Mailchimp Marketing API integration with OAuth2
- Campaign scheduling and performance tracking

HTTP Executor Enhancements

Native Basic Auth Support
- New authentication.type: basic with username_env and password_env fields
- Automatic base64 encoding of username:password at request time
- Works with Mailchimp, HubSpot, and any Basic Auth service
- No pre-computation needed; credentials stored separate in env vars
- Added to AuthConfig interface in packages/core/src/core/types.ts
Form-Encoded Request Bodies
- Automatic URLSearchParams conversion when Content-Type: application/x-www-form-urlencoded
- Fixes axios default JSON serialization for form submissions
- Validated with Twilio SMS/MMS live API testing
- Intelligent null/undefined filtering in templated fields
- Preserves JSON and custom formats for other Content-Types

Documentation & Examples

Provider READMEs
- packages/twilio/README.md
- packages/mailchimp/README.md
Integration Examples (Factory, Decorator, LangChain patterns)
- Twilio: twilio-factory.ts, twilio-decorator.ts, twilio-langchain.ts
- Mailchimp: mailchimp-factory.ts, mailchimp-decorator.ts, mailchimp-langchain.ts
- Real-world scenarios: Send SMS from agent, manage email subscribers, create campaigns
- Full error handling and credential validation

🛠 Fixes & Improvements

HTTP Executor (packages/core/src/executors/http-executor.ts)
- Enhanced request body handling for form encoding
- Automatic URLSearchParams conversion for form-encoded bodies
- Better parameter templating with string conversion for numbers/booleans
- Improved null/undefined filtering to prevent orphaned keys in templated objects
- Case-insensitive Content-Type detection
Mailchimp Documentation
- Updated API key logging for clarity (removed sensitive details)
- Adjusted asset paths for logo handling
- Corrected authentication method clarification

🔧 Technical Notes

Basic Auth Pattern: Set two env vars per service
- Example: MATIMO_MAILCHIMP_USERNAME=api_key_start, MATIMO_MAILCHIMP_PASSWORD=api_key_end
- Executor base64-encodes at request time; credentials never exposed in logs
Form Encoding: Automatically triggered when Content-Type: application/x-www-form-urlencoded detected
- No YAML changes needed; existing tools work transparently
- Objects in body converted to URLSearchParams by HTTP executor
- Numbers and booleans automatically converted to strings for form submission
Twilio Setup: Environment variables required
- TWILIO_ACCOUNT_SID — Find in Twilio Console
- TWILIO_AUTH_TOKEN — Find in Twilio Console
- TWILIO_FROM_NUMBER — Phone number to send from (E.164 format: +1234567890)
- TWILIO_TO_NUMBER — Optional; can also be passed as parameter
Mailchimp Setup: OAuth2 or API key
- API key: Set MATIMO_MAILCHIMP_API_KEY (Basic Auth with ‘user’ + key)
- OAuth2: Supported; token refresh handled transparently
Trial Accounts: Twilio trial accounts prepend “[Twilio] “ prefix to messages; upgrade to paid account to remove

⚠️ Breaking Changes

None.

📝 Migration Notes

New Tools: Twilio and Mailchimp available immediately after alpha.11 merge; no migration needed
Basic Auth: Existing tools can opt-in to native Basic Auth by updating YAML; backward compatible with hardcoded Authorization headers
Dependencies: Added twilio and mailchimp TypeScript types to packages/core/test/integration/; no user-facing API changes

v0.1.0-alpha.10

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

Released: February 21, 2026

🚀 Features

Notion Provider (packages/notion)
- Complete Notion tools package with 7 core tools for database and page operations
- Tools: notion_list_databases, notion_query_database, notion_create_page, notion_update_page, notion_get_page, notion_search, notion_create_comment
- Support for markdown content, database queries, page properties, icons, and covers
- Full OAuth2 or API key authentication
- Comprehensive YAML definitions with examples and output schemas
Notion Examples (Factory, Decorator, LangChain patterns)
- Three complete example scripts for integrating Notion tools
- Factory Pattern (notion-factory.ts) — Direct tool execution with database discovery and real operations
- Decorator Pattern (notion-decorator.ts) — Class-based @tool() decorator pattern
- LangChain Pattern (notion-langchain.ts) — AI agent with OpenAI GPT-4o-mini that auto-discovers databases
- Comprehensive README with setup, environment configuration, and troubleshooting
HTTP Executor Enhancements
- Improved parameter embedding for complex types (objects, arrays)
- Better handling of empty strings and null values in templating
- Structured response extraction with proper data validation
- Enhanced error normalization via new fromHttpError() factory method
Error Handling Improvements
- MatimoError class extended with optional cause field for error chaining
- New fromHttpError() helper to standardize HTTP/Axios errors into structured MatimoError
- Consistent error context preservation across executors

🛠 Fixes & Improvements

Notion Tools
- Auto-title generation for pages when DB properties are missing
- Validation of required parent parameter for create/update operations
- Proper markdown-to-block conversion for page content
- Fixed parameter templating for optional fields
HTTP Executor
- Fixed parameter validation to allow empty strings in templates
- Improved object/array embedding logic with explicit null/undefined checks
- Better error messages with original error details preserved
- Response schema validation via Zod
Tests
- Enhanced unit tests for HTTP executor with edge cases (empty strings, objects, arrays)
- Improved integration tests with better parameter validation
- Added response fixtures for multiple tool types
Examples
- Standardized convertToolsToLangChain() pattern across Slack, Gmail, and Notion examples
- LangChain examples now auto-discover resources (channels, databases) before creating agents
- Improved error handling and logging in all example patterns
Documentation
- Updated tool parameter documentation for clarity
- Added examples for complex parameter types (objects, arrays)
- Improved HTTP executor documentation with structured parameter embedding

🔧 Technical Notes

Parameter Templating: Object and array parameters are now properly embedded as JSON when indicated by parameter type in YAML
Error Chaining: Use MatimoError.cause and MatimoError.details.originalError to access the original exception
LangChain Integration: Secret injection pattern now supports complex types (objects) in addition to strings
Notion Authentication: Both API key and OAuth2 flows are fully supported; requires database sharing via Notion UI

⚠️ Breaking Changes

None.

📝 Migration Notes

Notion Tools: Set NOTION_API_KEY environment variable; share databases with your integration in Notion UI
Error Handling: Code catching generic Error types should check for MatimoError first; original errors available via error.cause
LangChain Examples: All examples now discover required context (database IDs, channel IDs) before creating agents; no changes needed if using as-is

v0.1.0-alpha.9

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

Released: February 19, 2026

🚀 Features

HubSpot Provider
- Added full HubSpot CRM integration as a new provider package (packages/hubspot).
- 50+ tools for Contacts, Companies, Deals, Tickets, Leads, Line Items, Invoices, Orders, Products, and Custom Objects (CRUD + list for each).
- All destructive tools (update, delete) require approval (requires_approval: true).
- OAuth2 and API key authentication supported.
- Comprehensive YAML tool definitions with examples and output schemas.
Examples
- New HubSpot example scripts for Factory, Decorator, and LangChain agent patterns (examples/tools/hubspot-*).
- Example scripts use real LLM agent pattern (OpenAI GPT-4o-mini via LangChain).
- Example and package READMEs for HubSpot, with setup, usage, and troubleshooting.
Testing
- Integration and unit tests for HubSpot tools (Jest, 85%+ coverage).
- Approval system tested for all destructive actions.
Documentation
- Full documentation for HubSpot tools in both packages/hubspot/README.md and examples/tools/hubspot/README.md.
- Updated main README.md to mention HubSpot support.
CI/CD
- Updated GitHub Actions workflow for npm releases and Discord notifications.

🛠 Fixes & Improvements

Lint: Removed all any types from test files, fixed all lint warnings.
Tests: Fixed all TypeScript errors in test files, all tests pass.
Approval: Confirmed all destructive HubSpot tools have requires_approval: true.
Package: Added HubSpot scripts to examples/tools/package.json.
Monorepo: Registered HubSpot in pnpm-workspace.yaml and pnpm-lock.yaml.

⚠️ Breaking Changes

None.

📝 Migration Notes

To use HubSpot tools, install dependencies and set MATIMO_HUBSPOT_API_KEY or configure OAuth2 as described in the package README.
Approval system is enforced for all destructive HubSpot actions; set MATIMO_APPROVAL_ENABLED=true to require approval.

v0.1.0-alpha.8

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

Released: February 18, 2026

🚀 Highlights

Unified approval system — Reworked approvals for destructive operations across core tools (edit, execute, read, search) with a single requires_approval flow and integration into MatimoInstance.
Structured logging — Integrated Winston for consistent, structured logs across core packages.
New GitHub provider tools — Added tools to manage repositories, releases, pull requests, and code search.
Examples & tests updated — Examples refactored to use the new approval flow; test coverage expanded across core modules.
CI / release fixes — Discord notification payload fixes and release workflow improvements.

📦 Packages

All publishable packages bumped to v0.1.0-alpha.8

🔧 Notable Changes

Removed legacy approval implementations (PathApprovalManager, SQLApprovalManager) and related tests in favor of the unified system.
Improved approval matching: glob -> regex conversion and expanded content-type checks to reduce false positives.
All tools updated to rely on the new approval flow; redundant tests removed.
Documentation: outdated File Operation Approval docs removed/updated to reflect the new approach.

🐛 Fixes

Fixed redundant Discord notification payload construction and formatting in release workflow.

v0.1.0-alpha.7.1

Patch: Discord release notifications + workflow improvements

Released: February 15, 2026

🔧 Updates

CI/CD Improvements

Fixed Discord webhook notifications — Proper JSON escaping for release notes with special characters
Dynamic package discovery — Automatically extracts publishable packages from pnpm-workspace.yaml instead of hardcoding
Improved error handling — Better escaping of quotes, backslashes, and newlines in release notes payload

Security & Robustness

All special characters (quotes, newlines, backslashes) in release notes are now safely escaped via jq
Webhook URL passed securely via GitHub Actions secrets
No hardcoded package lists — future packages auto-discovered

📊 Changes

npm-release.yml workflow improvements
All 7 packages bumped to v0.1.0-alpha.7.1

🐛 Bug Fixes

Discord notification JSON escaping
Date formatting in Discord footer
Package list generation from workspace configuration

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

New @matimo/postgres package — Production-ready PostgreSQL tool provider
postgres-execute-sql tool — Execute arbitrary SQL with parameterized query support for safety
Two authentication methods:
- Connection string: MATIMO_POSTGRES_URL=postgresql://...
- Separate env vars: MATIMO_POSTGRES_HOST, MATIMO_POSTGRES_PORT, MATIMO_POSTGRES_USER, MATIMO_POSTGRES_PASSWORD, MATIMO_POSTGRES_DB

SQL Approval Workflow System

SQLApprovalManager core class — Centralized approval management for destructive queries (DELETE, DROP, UPDATE, ALTER, TRUNCATE)
Interactive approval prompts — Real-time user approval for sensitive SQL operations
Smart detection — Automatically classifies queries as read-only or write/destructive
Session caching — Approve once per session, reduces repeated prompts
Auto-approval mode — Set MATIMO_SQL_AUTO_APPROVE=true for CI/CD environments
Custom approval callbacks — Integrate with your own approval logic via setApprovalCallback()

📚 Examples & Documentation

4 Complete Postgres Examples

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

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

Comprehensive Documentation

Postgres Package README — Complete tool specification, examples, authentication methods, error handling
Examples README — Sequential Discovery Pattern, Approval Workflow Guide, integration patterns
.env.example — Postgres configuration with both auth methods documented
Inline code comments — All examples extensively documented for easy understanding

CI/CD Enhancements

Discord webhook notifications — Automatic release notifications in Discord channel
Workflow improvement — npm-release workflow now posts Discord embed with release notes extracted from docs/RELEASES.md

📦 Package Updates

All 7 packages bumped to v0.1.0-alpha.7:
- matimo (root)
- @matimo/core
- @matimo/cli
- @matimo/slack
- @matimo/gmail
- @matimo/postgres ✨ NEW
- matimo-examples

🔧 Developer Experience

New APIs

SQLApprovalManager.isApproved(sql, mode) — Check if SQL is approved, prompts user if needed
SQLApprovalManager.setApprovalCallback() — Custom approval callback integration
setSQLApprovalManager() — Global singleton support for cross-module approval management

Configuration

Environment variables for Postgres connection (2 methods)
MATIMO_SQL_AUTO_APPROVE env var for automated environments
Graceful fallback handling for missing credentials

🐛 Fixes & Improvements

Error messages — Helpful hints for connection failures (ECONNREFUSED, missing role, missing database)
Non-TTY handling — Approval prompt properly rejects in non-interactive environments (CI/CD)
Parameter validation — Strict validation of SQL parameters in approval checks
Encoding support — Proper handling of connection string encoding for special characters in passwords

Postgres Package README — Tool specifications and usage
Examples README — Sequential discovery pattern, approval workflow
Tool Development Guide — How to create new tools

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

Approval flow for file operation tools — File read/write operations now require explicit approval to prevent unauthorized access
Command injection detection in execute tool — Added security validation to detect and block potentially malicious shell commands

Core Tools Architecture Overhaul

All core tools converted to function-type execution — Eliminates subprocess spawning and tsx PATH dependencies
Unified execution model — All core tools now use direct async function calls for better performance and error handling
Core tools suite expanded:
- execute — Execute shell commands with timeout, cwd control, and environment variables
- read — Read files with line range support, encoding detection, and large file handling
- edit — Edit/replace file contents with optional encoding and backup support
- search — Search files using grep patterns with line output and context display
- web — Fetch and parse web content with headers, cookies, and response validation
- calculator — Refactored to function-type for consistency

Execution Model Improvements

No external dependencies — Core tools no longer depend on tsx or other CLI tools
Direct in-process execution — Function-based tools execute directly without subprocess overhead
Better error handling — Native exception throwing instead of stdout/stderr parsing
Simpler type safety — Direct TypeScript function signatures for all tools

Testing & Examples

Comprehensive unit tests for all 5 new core tools (execute, read, edit, search, web)
Complete examples for all core tools in 3 integration patterns:
- Factory pattern (direct tool execution)
- Decorator pattern (class-based with @tool)
- LangChain pattern (AI agent integration)
Tests pass: 624+ test suite with 100% pass rate

Schema & Tool Loading Improvements

Enhanced ToolDefinitionSchema — Better parameter validation and default value handling
Improved tool caching — Tool packages cached for faster discovery and loading
Better tool discovery — Provider auto-discovery with efficient lookup
Passthrough validation removed — Stricter schema validation for tool definitions
Default parameters support — YAML definitions can now specify default values

Developer Experience

Unified core tools — Consistent execution model across all built-in tools
Cleaner imports — Tools properly structured under packages/core/tools/
commitlint updates — Added support for ‘example’ commit type in conventional commits

Quality & Reliability

Build fixes — Resolved issues from previous release
Lint fixes — Eliminated linting issues in updated code
Type safety — All tools properly typed with strict TypeScript checking

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)

calculator — Arithmetic operations (add, subtract, multiply, divide)
execute — Execute shell commands with full control
read — Read file contents with line ranges
edit — Edit/replace file contents
search — Search files by pattern
web — Fetch and parse web content

Provider Integrations (21+ tools)

slack — 16+ Slack tools (messaging, channels, users, etc.)
gmail — 5 Gmail tools (send, list, get, draft, delete)

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

✅ Improved test coverage across all packages
✅ No lint errors — Strict ESLint configuration
✅ 100% TypeScript strict mode — Full type safety
✅ Complete test coverage — Unit + integration tests for all tools
✅ All examples tested — 3 patterns × 6 core tools

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

Documentation Theme: Updated to Jekyll Slate theme for cleaner, simpler documentation rendering with GitHub Pages native support
Workspace Dependencies: Updated all peer dependencies across cli, gmail, and slack packages to use workspace:* versioning for better monorepo management
Version Bump: Official release of v0.1.0-alpha.5 with updated package versions across workspace
Release Workflow: Removed redundant custom GitHub Pages workflow in favor of GitHub’s native pages-build-deployment action
CNAME Configuration: Maintained custom domain setup for docs.matimo.dev
Package Documentation: Added comprehensive README documentation to core, slack, and gmail packages

Notes

Documentation now uses Slate theme for better compatibility with GitHub Pages
All workspace packages updated with consistent versioning
Simplified GitHub Actions workflow reduces maintenance and improves reliability

v0.1.0-alpha.4

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

Released: February 10, 2026

What’s New

Monorepo packaging: repository updated to a workspace layout. Core packages are split under packages/ and publishable as separate npm packages.
Matimo CLI: cli operations for list, search, install, help within Matimo eco-system.
CI publish update: GitHub Actions updated to publish workspace packages via pnpm -r publish so non-private workspace packages are released together.
Tools packages: Tool YAML and assets live under package/<provider-name> folders and are published as separate npm packages with in @matimo/<provider-name>
Examples & docs: Updated examples and docs to reflect packaging changes and improved quick-start guidance.
Build & test fixes: Ensured pnpm build and pnpm test run across workspace packages.

Notes

The release workflow now publishes all non-private workspace packages (filterable if needed).

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

16+ Slack tools across messaging, channel management, user queries, and topic management
Real OAuth2 integration with Slack workspace testing
Complete examples for all integration patterns
Comprehensive Slack API coverage: send messages, list/manage channels, set topics, list users, and more

Error Handling & Quality

Standardized MatimoError throughout SDK with machine-readable error codes
Consistent error structure across all executors and decorators
Error codes: INVALID_SCHEMA, FILE_NOT_FOUND, EXECUTION_FAILED, TOOL_NOT_FOUND, INVALID_PARAMETER
Proper error context without exposing sensitive data

Testing Improvements

Mocked HTTP tests - Removed real network calls from test suite
14 HTTP executor test cases with mocked axios responses
410 tests across 23 test suites with 100% pass rate
Deterministic, fast test execution with no external dependencies

Examples & Documentation

Examples directory renamed from langchain to tools - better reflects all three patterns
Comprehensive examples README - 300+ lines covering all integration patterns with code examples
Three integration patterns documented: Factory (direct), Decorator (class-based), LangChain (AI agents)
Tool reference tables for Slack and Gmail tools
Pattern comparison matrix and learning path
Configuration guides for Slack, Gmail, and OpenAI setup

Package Improvements

Examples package now uses published matimo (^0.1.0-alpha.3) instead of local path
Examples are now portable and work without building the SDK locally
Proper version constraints for all dependencies

What’s Improved from Alpha.2

Slack tools set
Unified error handling prevents silent failures
Test suite no longer makes real HTTP calls
Better developer experience with comprehensive examples
Documentation aligned with actual SDK capabilities

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

Slack (16+ tools): Send messages, manage channels, list topics, manage users, etc.
Gmail (5 tools): Send, list, get, draft, delete messages
Utilities: Calculator, echo, HTTP client

Documentation

Installation & Setup
Quick Start
Examples Guide - All three patterns with detailed walkthrough
SDK Patterns
OAuth2 Guide
API Reference

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

Improved npm publish workflow configuration (pre-releases currently publish under default ‘latest’ dist-tag)
Replaced deprecated GitHub Actions (softprops/action-gh-release@v2)
Proper semantic versioning for release titles
Fixed broken documentation links in releases

Package & Exports

Explicit package exports for main and MCP modules
Accurate npm description (reflects current Phase 1 scope)
Proper Node.js module resolution

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

OAuth2 handler with token injection
Providers: Google (Gmail), GitHub, Slack
Provider YAML configuration
Automatic token injection into requests

Tool System

YAML/JSON tool definitions with Zod validation
Command executor (shell commands with templating)
HTTP executor (REST APIs with OAuth2)
Provider definition system
Tool discovery and filtering

SDK Patterns

Factory pattern: const m = await matimo.init('./tools'); m.execute(toolName, params)
Decorator pattern: @tool('calculator') for class-based usage
Tool discovery, filtering, and search
Full TypeScript support with strict types

Tools Included

Gmail (5 tools): send, list, get, draft, delete
Utilities: calculator, echo, HTTP client
Provider configs: Google, GitHub, Slack

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

v0.1.0-alpha.13

🚀 Major Features

📚 Examples & Documentation

🧪 Test Coverage

📦 Packages

⚠️ Breaking Changes

🔗 Related

v0.1.0-alpha.12.1

🚀 Features

🧪 Test Coverage

📦 Packages

⚠️ Breaking Changes

v0.1.0-alpha.12

🚀 Major Features: MCP is Here

📚 Documentation

🔐 Security & Quality Improvements

📦 Packages

🎯 Key Achievements

⚠️ Breaking Changes

📝 Migration & Quick Start

v0.1.0-alpha.11

🚀 Features

🛠 Fixes & Improvements

🔧 Technical Notes

⚠️ Breaking Changes

📝 Migration Notes

v0.1.0-alpha.10

🚀 Features

🛠 Fixes & Improvements

🔧 Technical Notes

⚠️ Breaking Changes

📝 Migration Notes

v0.1.0-alpha.9

🚀 Features

🛠 Fixes & Improvements

⚠️ Breaking Changes

📝 Migration Notes

v0.1.0-alpha.8

🚀 Highlights

📦 Packages

🔧 Notable Changes

🐛 Fixes

Fixed redundant Discord notification payload construction and formatting in release workflow.

v0.1.0-alpha.7.1

🔧 Updates

CI/CD Improvements

Security & Robustness

📊 Changes

🐛 Bug Fixes

v0.1.0-alpha.7

🚀 New Features

Postgres Package & Tools

SQL Approval Workflow System

📚 Examples & Documentation

4 Complete Postgres Examples

Comprehensive Documentation

CI/CD Enhancements

📦 Package Updates

🔧 Developer Experience

New APIs

Configuration

🐛 Fixes & Improvements

🔗 Related Documentation

⚠️ Breaking Changes

v0.1.0-alpha.6

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)

After (alpha.6)

Tools Now Available

Core Utilities (6 tools)

Provider Integrations (21+ tools)

Examples

Execute Tool - All 3 Patterns