matimo 0.1.0-alpha.1 → 0.1.0-alpha.3

package/tools/slack/slack_join_channel/definition.yaml

@@ -0,0 +1,35 @@
+name: slack_join_channel
+description: |-
+  Add bot to a channel.
+  Uses conversations.join API method.
+  Bot must be invited to private channels by an admin first.
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    required: true
+    description: |-
+      Channel ID or name to join.
+      Format: C followed by alphanumeric (e.g., C123456)
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/conversations.join'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    channel: '{channel}'
+  timeout: 10000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: channels:manage
+  important: |-
+    - Public channels: Bot joins automatically
+    - Private channels: Admin must invite bot first
+    - Bot cannot join archived channels
+    - Use for gaining access before sending messages

package/tools/slack/slack_reply_to_message/definition.yaml

@@ -0,0 +1,49 @@
+name: slack_reply_to_message
+description: |-
+  Post a reply to a message thread.
+  Uses chat.postMessage API method with thread_ts parameter.
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    required: true
+    description: Channel ID containing the parent message
+  thread_ts:
+    type: string
+    required: true
+    description: |-
+      Timestamp of the parent message that starts the thread.
+      Use parent's ts value, never use a reply's ts value.
+  text:
+    type: string
+    required: false
+    description: |-
+      Reply text (optional if using blocks for rich formatting).
+      Recommended as fallback for notifications and accessibility.
+  blocks:
+    type: array
+    required: false
+    description: Block Kit JSON array for rich message formatting
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/chat.postMessage'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    channel: '{channel}'
+    text: '{text}'
+    thread_ts: '{thread_ts}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: chat:write
+  important: |-
+    - thread_ts must be parent message timestamp, not a reply
+    - Either text or blocks is recommended (both optional)
+    - Threads keep conversations organized by topic

package/tools/slack/slack_search_messages/definition.yaml

@@ -0,0 +1,46 @@
+name: slack_search_messages
+description: |-
+  Search across Slack message history.
+  Uses search.messages API method.
+  Supports filtering by channel, date range, and other criteria.
+version: '1.0.0'
+parameters:
+  query:
+    type: string
+    required: true
+    description: |-
+      Search query text.
+      Supports operators: from:@user, in:#channel, after:YYYY-MM-DD, etc.
+  sort:
+    type: string
+    required: false
+    description: |-
+      Sort results by: score (relevance, default) or timestamp
+  count:
+    type: number
+    required: false
+    description: |-
+      Number of results to return.
+      Default: 20, Max: 100
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/search.messages'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    query: '{query}'
+    sort: '{sort}'
+    count: '{count}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: search:read
+  important: |-
+    - Query supports advanced search operators
+    - Example: "from:@alice in:#engineering after:2024-01-01"
+    - Default sort is by relevance score

package/tools/slack/slack_send_channel_message/definition.yaml

@@ -0,0 +1,34 @@
+name: slack_send_channel_message
+description: Post a message (text, markdown, blocks) to a public/private Slack channel.
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    required: true
+    description: Channel ID or name to post the message to
+  text:
+    type: string
+    required: false
+    description: Plain-text message (optional if blocks provided, recommended as fallback for accessibility)
+  blocks:
+    type: array
+    required: false
+    description: Slack Block Kit JSON blocks (optional, used instead of text for rich formatting)
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/chat.postMessage'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    channel: '{channel}'
+    text: '{text}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  caution: Ensure `chat:write` scope and bot membership in private channels. Either text or blocks is recommended (not both required). Unresolved placeholders (e.g., {blocks} when not provided) will be sent as literal strings per Slack API contract.

package/tools/slack/slack_send_dm/definition.yaml

@@ -0,0 +1,37 @@
+name: slack_send_dm
+description: |-
+  Open or resume a direct message (DM) or multi-person direct message (MPIM) conversation.
+  Uses conversations.open API method.
+  After opening, use chat.postMessage to send the actual message.
+version: '1.0.0'
+parameters:
+  user:
+    type: string
+    required: true
+    description: |-
+      User ID or comma-separated user IDs for multi-person DM.
+      - 1 user ID: Creates a 1:1 DM
+      - Multiple user IDs (2-8): Creates an MPIM
+      Do not include the authenticated bot's user ID.
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/conversations.open'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    users: '{user}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: im:write, mpim:write
+  important: |-
+    - This method OPENS a conversation, it does not send a message
+    - Returns channel ID (D...) to use with chat.postMessage
+    - Subsequent calls with same users return existing conversation
+    - For 1:1 DMs, use user ID (U...), not DM channel ID (D...)

package/tools/slack/slack_set_channel_topic/definition.yaml

@@ -0,0 +1,40 @@
+name: slack_set_channel_topic
+description: |-
+  Set or update the topic (description) for a channel.
+  Uses conversations.setTopic API method.
+  Topic is displayed below the channel name in Slack UI.
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    required: true
+    description: Channel ID to update
+  topic:
+    type: string
+    required: true
+    description: |-
+      New topic text.
+      Max 250 characters.
+      Supports text formatting (@mentions, links, etc.)
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/conversations.setTopic'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    channel: '{channel}'
+    topic: '{topic}'
+  timeout: 10000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: conversations:manage
+  important: |-
+    - Bot must be channel member to set topic
+    - Topic limited to 250 characters
+    - Visible in channel info below channel name

package/tools/slack/slack_upload_file/definition.yaml

@@ -0,0 +1,152 @@
+name: slack_upload_file
+description: |-
+  Upload a file to Slack using the modern files API.
+  
+  This tool provides a simplified interface to upload files to Slack.
+  It uses the latest Slack file upload API (files.getUploadURLExternal + files.completeUploadExternal)
+  introduced in 2024 as the recommended approach.
+  
+  FEATURES:
+  ✅ Supports files up to 500MB
+  ✅ Share directly to channels during upload
+  ✅ Add file title and initial comment
+  ✅ Better error handling and retry logic
+  ✅ Modern, official Slack recommended API
+  ✅ Future-proof (won't be deprecated)
+  
+  REQUIRED SCOPES:
+  • files:write - Required to upload files
+  
+  API REFERENCE:
+  https://docs.slack.dev/reference/methods/files.getUploadURLExternal
+  https://docs.slack.dev/reference/methods/files.completeUploadExternal
+version: '1.0.0'
+parameters:
+  filename:
+    type: string
+    required: true
+    description: |-
+      Name of the file (e.g., "report.pdf", "data.json")
+      Used as the file name in Slack
+  file_size:
+    type: number
+    required: true
+    description: |-
+      Size of the file in bytes.
+      Maximum 500MB (524,288,000 bytes)
+      Must match actual file size for upload
+  channel_id:
+    type: string
+    required: true
+    description: |-
+      Channel ID to share file with.
+      Example: "C024BE91L"
+      Bot must be a member of the channel
+  title:
+    type: string
+    required: false
+    description: |-
+      Title for the file in Slack (separate from filename).
+      If not provided, filename is used as title.
+      Supports up to 255 characters
+  initial_comment:
+    type: string
+    required: false
+    description: |-
+      Message text to introduce the file in the channel.
+      Example: "Here's the quarterly report PDF"
+      Supports markdown formatting
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/files.getUploadURLExternal'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    filename: '{filename}'
+    length: '{file_size}'
+  timeout: 30000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+output_schema:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      description: Whether the request was successful
+    upload_url:
+      type: string
+      description: URL where to upload the file binary
+    file_id:
+      type: string
+      description: Unique identifier for the uploaded file
+    upload_url_expires:
+      type: number
+      description: Unix timestamp when the upload URL expires
+notes:
+  env: SLACK_BOT_TOKEN
+  
+  api_version: |-
+    Modern API (Current - Recommended)
+    • Uses: files.getUploadURLExternal (get upload URL)
+    • Uses: files.completeUploadExternal (complete upload)
+    • Introduced: 2024
+    • Status: Official Slack recommendation
+    • Maintenance: Actively maintained
+  
+  scopes_required: |-
+    • files:write - Required to upload files
+    • channels:read - Optional, to validate channel IDs
+  
+  usage_pattern: |-
+    TWO-STEP PROCESS:
+    
+    1. Get Upload URL (this tool):
+       Call with: filename, file_size, channel_id
+       Returns: upload_url, file_id, upload_url_expires
+    
+    2. Upload File Binary (manual/SDK):
+       Method: HTTP PUT to upload_url
+       Headers: Content-Type: application/octet-stream
+       Body: Raw file binary content
+    
+    3. Complete Upload (use slack_complete_file_upload):
+       Call with: file_id, channel_id, title, initial_comment
+       Returns: File object with sharing info
+  
+  important: |-
+    • Bot requires files:write scope
+    • File size must match file_size parameter exactly
+    • Upload URL expires (check upload_url_expires)
+    • If URL expires, start over with fresh getUploadURLExternal call
+    • Channel ID must be one where bot is a member
+  
+  best_practices: |-
+    DO:
+    ✅ Check upload_url_expires before uploading large files
+    ✅ Use Content-Type: application/octet-stream for PUT
+    ✅ Verify file_size matches actual file size
+    ✅ Include initial_comment for context when sharing
+    ✅ Validate channel_id exists before uploading
+    
+    DON'T:
+    ❌ Use channels bot hasn't joined
+    ❌ Wait too long between getting URL and uploading (URLs expire ~2 hours)
+    ❌ Forget to call slack_complete_file_upload after upload
+    ❌ Include sensitive data in initial_comment
+  
+  limitations: |-
+    • Maximum file size: 500MB
+    • Upload URL valid for approximately 2 hours
+    • Bot must be member of channel to share
+    • Response format follows Slack Web API standards
+  
+  changelog: |-
+    Version 1.0.0 (Feb 2026):
+    • Updated to use modern files.getUploadURLExternal API
+    • Replaces deprecated files.upload (sunset Nov 12, 2025)
+    • Supports up to 500MB files
+    • Better error handling

package/docs/Gemfile

@@ -1,5 +0,0 @@
-source "https://rubygems.org"
-
-gem "jekyll", "~> 4.3.0"
-gem "jekyll-theme-slate"
-gem "webrick", "~> 1.8"

package/docs/RELEASES.md

@@ -1,69 +0,0 @@
-# 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
-
-```bash
-npm install matimo@0.1.0-alpha.1
-pnpm add matimo@0.1.0-alpha.1
-```
-
-## Quick Start
-
-```typescript
-import { matimo } from 'matimo';
-
-const m = await matimo.init('./tools');
-const result = await m.execute('calculator', { 
-  operation: 'add', a: 5, b: 3 
-});
-```
-
-## Documentation
-
-- [Installation & Setup](./getting-started/installation.md)
-- [Quick Start](./getting-started/QUICK_START.md)
-- [SDK Patterns](./user-guide/SDK_PATTERNS.md)
-- [OAuth2 Guide](./architecture/OAUTH.md)
-- [API Reference](./api-reference/SDK.md)
-- [Examples](../examples/)
-
-
-## Known Limitations
-
-This is an **alpha release**. Not recommended for production without thorough testing.
-
-See [Roadmap](./ROADMAP.md) for future features.
-
-## Contributing
-
-[Contributing Guide](../CONTRIBUTING.md) | [Report Issues](https://github.com/tallclub/matimo/issues)

package/docs/ROADMAP.md

@@ -1,138 +0,0 @@
-# Matimo Roadmap
-
-## v0.1.0-alpha.1 (Current Release)
-
-### ✅ Core Features Implemented
-
-**OAuth2 Authentication**
-- OAuth2 handler with token management
-- Provider-agnostic configuration via YAML
-- Multi-provider support (Google, GitHub, Slack)
-- Token injection system for tools
-
-**Tool System**
-- YAML-based tool definitions with Zod validation
-- Tool loader and registry
-- Command executor (shell commands + templating)
-- HTTP executor (REST APIs with OAuth2 support)
-- Parameter encoding utilities
-
-**SDK Patterns**
-- Factory pattern (recommended for simple use cases)
-- Decorator pattern (@tool decorators for class-based code)
-- Tool discovery and filtering
-- Full TypeScript type safety (zero `any` types)
-
-**Tool Examples**
-- Gmail tools (list, get, send, create-draft, delete)
-- GitHub provider configuration
-- Slack provider configuration
-- Calculator and echo tools (reference implementations)
-
-**Quality Assurance**
-- 100% test passing
-- Full TypeScript strict mode enforcement
-- ESLint clean with zero warnings
-- Prettier formatting
-- Zod schema validation for all definitions
-
-**Documentation**
-- Quick start guide
-- API reference
-- Tool specification
-- OAuth2 implementation guide
-- Decorator pattern guide
-- Contributing guide
-- Security guidelines
-
----
-
-## Future Release (not in specific order)
-
-### 🔜 Planned Features
-
-**CLI Tool**
-- `matimo list` - List all tools
-- `matimo execute` - Execute tools from command line
-- `matimo validate` - Validate tool YAML files
-- `matimo test` - Test tool execution locally
-
-**MCP (Model Context Protocol) Server**
-- Native MCP server 
-- Tool discovery via MCP
-- Automatic tool calling
-- Session management
-
-**Framework Integrations**
-- CrewAI integration examples
-- Vercel AI SDK integration
-- Custom framework patterns
-- Framework-specific documentation
-
-**Advanced Features**
-- Rate limiting (token bucket algorithm)
-- Health monitoring (API schema drift detection)
-- Token refresh automation
-- Error recovery strategies
-
-**REST API Server**
-- HTTP endpoints for tool execution
-- Async job execution
-- Webhook support
-- OpenAPI documentation
-
-**Python SDK**
-- Python implementation with same YAML definitions
-- LangChain Python integration
-- CrewAI Python support
-- Feature parity with Node.js SDK
-
-**Tool Marketplace**
-- Distributed tool registry
-- Tool publishing and versioning
-- Community tool submissions
-- Tool ratings and reviews
-
-**Deployment**
-- Docker images and Dockerfile examples
-- Kubernetes deployment guides
-- CI/CD integration examples
-- Production deployment patterns
-
-**Ecosystem Maturity**
-- Automated schema translation (OpenAPI → Matimo YAML)
-- Performance optimizations
-- Enterprise features (audit logs, rate limiting)
-
-**Skills/Workflows**
-- Tool composition/chaining
-- Conditional execution
-- Error handling workflows
-- Advanced orchestration
-
-
-## How to Use This Roadmap
-
-- **v0.1.0-alpha.1**: Use current implementation for OAuth2, tool execution, and SDK patterns
-- **Future Releases**: These are planned but not yet implemented. Contributions welcome!
-- **Contributing**: See [CONTRIBUTING.md](../CONTRIBUTING.md) for how to help
-
----
-
-## Release Thoughts
-
-```
-v0.1.0-alpha.1  Feb 2026 (Current)
-    ↓
-v0.1.0-alpha.2  3rd week Feb 2026.     
-    ↓
-v0.1.0-alpha.3  1st week Mar 2026.    
-    ↓
-v0.1.0     End of March 2026. 
-```
-
----
-
-## Contributing to the Roadmap
-
-Have ideas? [Open a GitHub Discussion](https://github.com/tallclub/matimo/discussions) to propose features for future releases.

package/docs/_config.yml

@@ -1,27 +0,0 @@
-theme: jekyll-theme-slate
-title: Matimo - AI Tools Ecosystem
-description: Define tools once in YAML, use them everywhere
-show_downloads: true
-google_analytics: false
-
-# Matimo Documentation
-url: "https://tallclub.github.io"
-baseurl: "/matimo"
-repository: "tallclub/matimo"
-
-# Build settings
-markdown: kramdown
-highlighter: rouge
-
-# Navigation
-nav:
-  - text: "Home"
-    url: "/"
-  - text: "Getting Started"
-    url: "/getting-started/"
-  - text: "Documentation"
-    url: "/"
-  - text: "GitHub"
-    url: "https://github.com/tallclub/matimo"
-  - text: "npm"
-    url: "https://www.npmjs.com/package/matimo"