matimo-slack 0.1.0__tar.gz

matimo_slack-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Dependencies
+**/node_modules/
+package-lock.json
+yarn.lock
+
+# Build output
+**/dist/
+*.tsbuildinfo
+
+# Python compiled / build
+**/__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+**/build/
+**/.eggs/
+**/.venv/
+**/.mypy_cache/
+**/.ruff_cache/
+**/.pytest_cache/
+
+# Test coverage
+**/coverage/
+**/.nyc_output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+typescript/examples/mcp/matimo-tools/.matimo-approvals.json
+typescript/examples/mcp/matimo-tools/fetch-weather/definition.yaml
+typescript/examples/mcp/matimo-tools/npm_downloads/definition.yaml
+typescript/examples/mcp/matimo-tools/skills/ecosystem-health/SKILL.md
+typescript/examples/mcp/matimo-tools/skills/matimo-health-check/SKILL.md
+typescript/examples/mcp/matimo-tools/skills/moltbook-identity/SKILL.md
+typescript/packages/cli/.matimo/certs/server.crt
+typescript/packages/cli/.matimo/certs/server.key
+typescript/examples/mcp/.matimo/certs/server.crt
+typescript/examples/mcp/.matimo/certs/server.key

matimo_slack-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: matimo-slack
+Version: 0.1.0
+Summary: Matimo provider — Slack tools (send messages, manage channels, users)
+License: MIT
+Keywords: agents,ai,matimo,slack,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Requires-Dist: matimo-core<0.2.0,>=0.1.0
+Description-Content-Type: text/markdown
+
+# matimo-slack
+
+> Slack tools for [Matimo](https://matimo.dev) — send messages, manage channels, upload files, and more.
+
+[![PyPI](https://img.shields.io/pypi/v/matimo-slack)](https://pypi.org/project/matimo-slack/)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+
+---
+
+## Installation
+
+```bash
+pip install matimo matimo-slack
+```
+
+---
+
+## Available Tools (19 Total)
+
+| Category | Tool | Description |
+|----------|------|-------------|
+| **Messaging** | `slack_send_channel_message` | Post message with markdown/blocks |
+| | `slack-send-message` | Post plain message to channel |
+| | `slack_reply_to_message` | Reply in thread |
+| | `slack_send_dm` | Send direct message |
+| **Channels** | `slack-list-channels` | List all channels/DMs |
+| | `slack_create_channel` | Create public/private channel |
+| | `slack_join_channel` | Add bot to channel |
+| | `slack_set_channel_topic` | Update channel description/topic |
+| **Files** | `slack_upload_file` | Upload file (modern API) |
+| | `slack_upload_file_v2` | Get upload URL for large files |
+| | `slack_complete_file_upload` | Complete upload and share to channel |
+| **Reading** | `slack_get_channel_history` | Read messages from channel |
+| | `slack_get_thread_replies` | Get thread replies |
+| | `slack_search_messages` | Search message history |
+| **Reactions** | `slack_add_reaction` | Add emoji reaction to message |
+| | `slack_get_reactions` | Get reactions on a message |
+| **Users** | `slack_get_user_info` | Get user profile details |
+| | `slack-get-user` | Alias of `slack_get_user_info` |
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from matimo import Matimo
+from matimo_slack import get_tools_path
+
+async def main():
+    matimo = await Matimo.init(get_tools_path())
+
+    # Send a message
+    await matimo.execute('slack_send_channel_message', {
+        'channel': '#general',
+        'text': 'Hello from Matimo!',
+    })
+
+    # List channels
+    result = await matimo.execute('slack-list-channels', {})
+    print(result)
+
+asyncio.run(main())
+```
+
+---
+
+## Authentication
+
+All tools authenticate using a Slack Bot Token:
+
+```bash
+export SLACK_BOT_TOKEN="xoxb-your-bot-token"
+```
+
+### Setting Up a Slack App
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → From scratch
+2. Navigate to **OAuth & Permissions** and add scopes (see table below)
+3. Click **Install to Workspace** and copy the **Bot User OAuth Token**
+4. Set `SLACK_BOT_TOKEN` in your environment
+
+### Required OAuth Scopes
+
+| Tool | Slack API Method | Required Scopes |
+|------|-----------------|-----------------|
+| `slack_send_channel_message` / `slack-send-message` | `chat.postMessage` | `chat:write` |
+| `slack_reply_to_message` | `chat.postMessage` | `chat:write` |
+| `slack_send_dm` | `conversations.open` + `chat.postMessage` | `im:write`, `chat:write` |
+| `slack-list-channels` | `conversations.list` | `channels:read`, `groups:read`, `im:read`, `mpim:read` |
+| `slack_create_channel` | `conversations.create` | `channels:manage` |
+| `slack_join_channel` | `conversations.join` | `channels:join` |
+| `slack_set_channel_topic` | `conversations.setTopic` | `channels:write.topic` |
+| `slack_upload_file` / `slack_upload_file_v2` | `files.getUploadURLExternal` | `files:write` |
+| `slack_complete_file_upload` | `files.completeUploadExternal` | `files:write` |
+| `slack_get_channel_history` | `conversations.history` | `channels:history` |
+| `slack_get_thread_replies` | `conversations.replies` | `channels:history` |
+| `slack_search_messages` | `search.messages` | `search:read` |
+| `slack_add_reaction` | `reactions.add` | `reactions:write` |
+| `slack_get_reactions` | `reactions.get` | `reactions:read` |
+| `slack_get_user_info` / `slack-get-user` | `users.info` | `users:read` |
+
+---
+
+## LangChain Agent Example
+
+```python
+from matimo import Matimo
+from matimo_slack import get_tools_path
+from matimo.integrations.langchain import convert_tools_to_langchain
+from langchain_openai import ChatOpenAI
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain_core.prompts import ChatPromptTemplate
+
+matimo = await Matimo.init(get_tools_path())
+lc_tools = convert_tools_to_langchain(
+    matimo.list_tools(),
+    matimo,
+    credentials={'SLACK_BOT_TOKEN': os.environ['SLACK_BOT_TOKEN']},
+)
+llm = ChatOpenAI(model='gpt-4o-mini')
+prompt = ChatPromptTemplate.from_messages([
+    ('system', 'You are a Slack assistant.'),
+    ('human', '{input}'),
+    ('placeholder', '{agent_scratchpad}'),
+])
+agent = create_tool_calling_agent(llm, lc_tools, prompt)
+executor = AgentExecutor(agent=agent, tools=lc_tools)
+result = await executor.ainvoke({'input': 'List all public channels'})
+```
+
+---
+
+## Usage Notes
+
+- The bot must be **a member of a channel** before it can post messages or read history
+- Use `slack_upload_file` (not the deprecated `files.upload`) for file uploads
+- `slack_search_messages` requires the `search:read` scope which needs special approval from Slack
+- Rate limits apply — add delays between rapid API calls in bulk operations
+
+---
+
+## Documentation
+
+- [Slack Integration Guide](https://matimo.dev/docs) 
+- [Slack Web API Reference](https://api.slack.com/methods)
+- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/native/slack)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-slack/
+- **GitHub:** https://github.com/tallclub/matimo
+- **Slack API Docs:** https://api.slack.com/
+

matimo_slack-0.1.0/README.md

@@ -0,0 +1,157 @@
+# matimo-slack
+
+> Slack tools for [Matimo](https://matimo.dev) — send messages, manage channels, upload files, and more.
+
+[![PyPI](https://img.shields.io/pypi/v/matimo-slack)](https://pypi.org/project/matimo-slack/)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+
+---
+
+## Installation
+
+```bash
+pip install matimo matimo-slack
+```
+
+---
+
+## Available Tools (19 Total)
+
+| Category | Tool | Description |
+|----------|------|-------------|
+| **Messaging** | `slack_send_channel_message` | Post message with markdown/blocks |
+| | `slack-send-message` | Post plain message to channel |
+| | `slack_reply_to_message` | Reply in thread |
+| | `slack_send_dm` | Send direct message |
+| **Channels** | `slack-list-channels` | List all channels/DMs |
+| | `slack_create_channel` | Create public/private channel |
+| | `slack_join_channel` | Add bot to channel |
+| | `slack_set_channel_topic` | Update channel description/topic |
+| **Files** | `slack_upload_file` | Upload file (modern API) |
+| | `slack_upload_file_v2` | Get upload URL for large files |
+| | `slack_complete_file_upload` | Complete upload and share to channel |
+| **Reading** | `slack_get_channel_history` | Read messages from channel |
+| | `slack_get_thread_replies` | Get thread replies |
+| | `slack_search_messages` | Search message history |
+| **Reactions** | `slack_add_reaction` | Add emoji reaction to message |
+| | `slack_get_reactions` | Get reactions on a message |
+| **Users** | `slack_get_user_info` | Get user profile details |
+| | `slack-get-user` | Alias of `slack_get_user_info` |
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from matimo import Matimo
+from matimo_slack import get_tools_path
+
+async def main():
+    matimo = await Matimo.init(get_tools_path())
+
+    # Send a message
+    await matimo.execute('slack_send_channel_message', {
+        'channel': '#general',
+        'text': 'Hello from Matimo!',
+    })
+
+    # List channels
+    result = await matimo.execute('slack-list-channels', {})
+    print(result)
+
+asyncio.run(main())
+```
+
+---
+
+## Authentication
+
+All tools authenticate using a Slack Bot Token:
+
+```bash
+export SLACK_BOT_TOKEN="xoxb-your-bot-token"
+```
+
+### Setting Up a Slack App
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → From scratch
+2. Navigate to **OAuth & Permissions** and add scopes (see table below)
+3. Click **Install to Workspace** and copy the **Bot User OAuth Token**
+4. Set `SLACK_BOT_TOKEN` in your environment
+
+### Required OAuth Scopes
+
+| Tool | Slack API Method | Required Scopes |
+|------|-----------------|-----------------|
+| `slack_send_channel_message` / `slack-send-message` | `chat.postMessage` | `chat:write` |
+| `slack_reply_to_message` | `chat.postMessage` | `chat:write` |
+| `slack_send_dm` | `conversations.open` + `chat.postMessage` | `im:write`, `chat:write` |
+| `slack-list-channels` | `conversations.list` | `channels:read`, `groups:read`, `im:read`, `mpim:read` |
+| `slack_create_channel` | `conversations.create` | `channels:manage` |
+| `slack_join_channel` | `conversations.join` | `channels:join` |
+| `slack_set_channel_topic` | `conversations.setTopic` | `channels:write.topic` |
+| `slack_upload_file` / `slack_upload_file_v2` | `files.getUploadURLExternal` | `files:write` |
+| `slack_complete_file_upload` | `files.completeUploadExternal` | `files:write` |
+| `slack_get_channel_history` | `conversations.history` | `channels:history` |
+| `slack_get_thread_replies` | `conversations.replies` | `channels:history` |
+| `slack_search_messages` | `search.messages` | `search:read` |
+| `slack_add_reaction` | `reactions.add` | `reactions:write` |
+| `slack_get_reactions` | `reactions.get` | `reactions:read` |
+| `slack_get_user_info` / `slack-get-user` | `users.info` | `users:read` |
+
+---
+
+## LangChain Agent Example
+
+```python
+from matimo import Matimo
+from matimo_slack import get_tools_path
+from matimo.integrations.langchain import convert_tools_to_langchain
+from langchain_openai import ChatOpenAI
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain_core.prompts import ChatPromptTemplate
+
+matimo = await Matimo.init(get_tools_path())
+lc_tools = convert_tools_to_langchain(
+    matimo.list_tools(),
+    matimo,
+    credentials={'SLACK_BOT_TOKEN': os.environ['SLACK_BOT_TOKEN']},
+)
+llm = ChatOpenAI(model='gpt-4o-mini')
+prompt = ChatPromptTemplate.from_messages([
+    ('system', 'You are a Slack assistant.'),
+    ('human', '{input}'),
+    ('placeholder', '{agent_scratchpad}'),
+])
+agent = create_tool_calling_agent(llm, lc_tools, prompt)
+executor = AgentExecutor(agent=agent, tools=lc_tools)
+result = await executor.ainvoke({'input': 'List all public channels'})
+```
+
+---
+
+## Usage Notes
+
+- The bot must be **a member of a channel** before it can post messages or read history
+- Use `slack_upload_file` (not the deprecated `files.upload`) for file uploads
+- `slack_search_messages` requires the `search:read` scope which needs special approval from Slack
+- Rate limits apply — add delays between rapid API calls in bulk operations
+
+---
+
+## Documentation
+
+- [Slack Integration Guide](https://matimo.dev/docs) 
+- [Slack Web API Reference](https://api.slack.com/methods)
+- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/native/slack)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-slack/
+- **GitHub:** https://github.com/tallclub/matimo
+- **Slack API Docs:** https://api.slack.com/
+

matimo_slack-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "matimo-slack"
+version = "0.1.0"
+description = "Matimo provider — Slack tools (send messages, manage channels, users)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["ai", "tools", "agents", "matimo", "slack"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "matimo-core>=0.1.0,<0.2.0",
+]
+
+[project.entry-points."matimo.providers"]
+slack = "matimo_slack:get_tools_path"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/matimo_slack"]

matimo_slack-0.1.0/src/matimo_slack/__init__.py

@@ -0,0 +1,17 @@
+"""Matimo slack provider — exposes the path to YAML tool definitions."""
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+
+def get_tools_path() -> str:
+    """Return the absolute path to the bundled slack tool definitions."""
+    try:
+        ref = importlib.resources.files("matimo_slack") / "tools"
+        return str(ref)
+    except Exception:
+        return str(Path(__file__).parent / "tools")
+
+
+__all__ = ["get_tools_path"]

matimo_slack-0.1.0/src/matimo_slack/tools/get-user/definition.yaml

@@ -0,0 +1,31 @@
+name: slack-get-user
+description: |-
+  Retrieve detailed information about a Slack user.
+  Uses users.info API method.
+version: '1.0.0'
+parameters:
+  user:
+    type: string
+    description: |-
+      Slack user ID to lookup.
+      Format: U followed by alphanumeric string (e.g., U123456)
+    required: true
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/users.info'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    user: '{user}'
+  timeout: 10000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: users:read
+  important: |-
+    - Use user ID (U...), not username (deprecated in Slack)
+    - Returns profile info, presence, and user details

matimo_slack-0.1.0/src/matimo_slack/tools/list-channels/definition.yaml

@@ -0,0 +1,46 @@
+name: slack-list-channels
+description: |-
+  List all Slack conversations (channels, direct messages, multi-person DMs).
+  Uses conversations.list API method. Supports filtering by type and pagination.
+version: '1.0.0'
+parameters:
+  types:
+    type: string
+    description: |-
+      Comma-separated conversation types to include.
+      Valid values: public_channel, private_channel, mpim, im
+      Default: public_channel
+    required: false
+  limit:
+    type: number
+    description: |-
+      Maximum number of items to return (max 1000).
+      We recommend no more than 200 results at a time.
+      Default: 100
+    required: false
+  cursor:
+    type: string
+    description: Pagination cursor for fetching next page (from response_metadata.next_cursor)
+    required: false
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/conversations.list'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    types: '{types}'
+    limit: '{limit}'
+    cursor: '{cursor}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: channels:read, groups:read, im:read, mpim:read
+  important: |-
+    - The bot must be a member of private channels to list them
+    - Use cursor-based pagination for large result sets
+    - Supports org-level tokens with team_id parameter

matimo_slack-0.1.0/src/matimo_slack/tools/send-message/definition.yaml

@@ -0,0 +1,30 @@
+name: slack-send-message
+description: Post a message to a Slack channel using the Web API (chat.postMessage)
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    description: Channel ID or user ID to send the message to
+    required: true
+  text:
+    type: string
+    description: Plain-text message to post (optional if blocks provided, recommended as fallback for accessibility)
+    required: false
+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 the bot token has chat:write scope. Either text or blocks is required (Slack API will reject if neither provided). Unresolved placeholders will be sent as literal strings.'

matimo_slack-0.1.0/src/matimo_slack/tools/slack_add_reaction/definition.yaml

@@ -0,0 +1,45 @@
+name: slack_add_reaction
+description: |-
+  Add an emoji reaction to a message or file.
+  Uses reactions.add API method.
+version: '1.0.0'
+parameters:
+  name:
+    type: string
+    required: true
+    description: |-
+      Emoji name without colons.
+      Examples: thumbsup, heart, rocket, thinking_face
+  channel:
+    type: string
+    required: true
+    description: Channel ID containing the message
+  timestamp:
+    type: string
+    required: true
+    description: |-
+      Message timestamp (ts value).
+      Format: Unix timestamp with decimal precision
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/reactions.add'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    name: '{name}'
+    channel: '{channel}'
+    timestamp: '{timestamp}'
+  timeout: 10000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: reactions:write
+  important: |-
+    - Emoji name must be valid and enabled in workspace
+    - Works on messages and file reactions
+    - Cannot add same reaction twice

matimo_slack-0.1.0/src/matimo_slack/tools/slack_create_channel/definition.yaml

@@ -0,0 +1,41 @@
+name: slack_create_channel
+description: |-
+  Create a new public or private Slack channel.
+  Uses conversations.create API method.
+version: '1.0.0'
+parameters:
+  name:
+    type: string
+    required: true
+    description: |-
+      Name of the channel.
+      Must be lowercase letters, numbers, hyphens, underscores only.
+      Max 80 characters.
+  is_private:
+    type: boolean
+    required: false
+    description: |-
+      Set to true to create a private channel.
+      Default: false (creates public channel)
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/conversations.create'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    name: '{name}'
+    is_private: '{is_private}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: channels:manage, channels:write, groups:write
+  important: |-
+    - Store both returned channel ID and name from response
+    - Channel names are validated by Slack
+    - Private channels require additional scopes

matimo_slack-0.1.0/src/matimo_slack/tools/slack_get_channel_history/definition.yaml

@@ -0,0 +1,58 @@
+name: slack_get_channel_history
+description: |-
+  Retrieve message history from a channel.
+  Uses conversations.history API method.
+  Supports time range filtering and cursor-based pagination.
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    required: true
+    description: Channel ID to fetch messages from
+  limit:
+    type: number
+    required: false
+    default: 50
+    description: |-
+      Maximum number of messages to return.
+      Default: 50, Max: 1000
+  latest:
+    type: string
+    required: false
+    description: |-
+      End timestamp (inclusive).
+      Messages up to this timestamp. Now by default.
+  oldest:
+    type: string
+    required: false
+    description: |-
+      Start timestamp (inclusive).
+      Messages from this timestamp onward.
+  cursor:
+    type: string
+    required: false
+    description: Pagination cursor from response_metadata.next_cursor
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/conversations.history'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    channel: '{channel}'
+    limit: '{limit}'
+    latest: '{latest}'
+    oldest: '{oldest}'
+    cursor: '{cursor}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: conversations:history
+  important: |-
+    - Messages returned in reverse chronological order
+    - Use cursor-based pagination for large result sets
+    - Timestamps in Unix format with decimal precision

matimo_slack-0.1.0/src/matimo_slack/tools/slack_get_reactions/definition.yaml

@@ -0,0 +1,36 @@
+name: slack_get_reactions
+description: |-
+  Retrieve all emoji reactions on a message or file.
+  Uses reactions.get API method.
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    required: true
+    description: Channel ID containing the message
+  timestamp:
+    type: string
+    required: true
+    description: |-
+      Message timestamp (ts value).
+      Format: Unix timestamp with decimal precision (e.g., 1503435956.000247)
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/reactions.get'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    channel: '{channel}'
+    timestamp: '{timestamp}'
+  timeout: 10000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: reactions:read
+  important: |-
+    - Returns all reactions and who added them
+    - Works for messages and file reactions

matimo_slack-0.1.0/src/matimo_slack/tools/slack_get_thread_replies/definition.yaml

@@ -0,0 +1,45 @@
+name: slack_get_thread_replies
+description: |-
+  Retrieve all replies in a message thread.
+  Uses conversations.replies API method.
+  Includes the parent message as first result.
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    required: true
+    description: Channel ID containing the thread
+  ts:
+    type: string
+    required: true
+    description: |-
+      Timestamp of the parent message (thread root).
+      Include parent message ts, not a reply ts.
+  limit:
+    type: number
+    required: false
+    description: |-
+      Maximum number of messages to return.
+      Default: 100, Max: 1000
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/conversations.replies'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    channel: '{channel}'
+    ts: '{ts}'
+    limit: '{limit}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: conversations:history
+  important: |-
+    - ts must be parent message, not a reply
+    - Parent message included in response
+    - Sorted by timestamp

matimo_slack-0.1.0/src/matimo_slack/tools/slack_get_user_info/definition.yaml

@@ -0,0 +1,32 @@
+name: slack_get_user_info
+description: |-
+  Retrieve detailed information about a Slack user.
+  Uses users.info API method.
+  (Alias: slack-get-user)
+version: '1.0.0'
+parameters:
+  user:
+    type: string
+    required: true
+    description: |-
+      Slack user ID to retrieve info for.
+      Format: U followed by alphanumeric string (e.g., U123456)
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/users.info'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    user: '{user}'
+  timeout: 10000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: users:read
+  important: |-
+    - Use user ID (U...), not username (deprecated)
+    - Returns profile, presence, and user metadata

matimo_slack-0.1.0/src/matimo_slack/tools/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

matimo_slack-0.1.0/src/matimo_slack/tools/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

matimo_slack-0.1.0/src/matimo_slack/tools/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

matimo_slack-0.1.0/src/matimo_slack/tools/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.

matimo_slack-0.1.0/src/matimo_slack/tools/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...)

matimo_slack-0.1.0/src/matimo_slack/tools/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

matimo_slack-0.1.0/src/matimo_slack/tools/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