matimo-notion 0.1.0__tar.gz

matimo_notion-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_notion-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: matimo-notion
+Version: 0.1.0
+Summary: Matimo provider — Notion tools (pages, databases, comments)
+License: MIT
+Keywords: agents,ai,matimo,notion,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-notion
+
+> Notion tools for [Matimo](https://matimo.dev) — create pages, query databases, search, and manage content.
+
+[![PyPI](https://img.shields.io/pypi/v/matimo-notion)](https://pypi.org/project/matimo-notion/)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+
+---
+
+## Installation
+
+```bash
+pip install matimo matimo-notion
+```
+
+---
+
+## Available Tools (7 Total)
+
+| Tool | Description |
+|------|-------------|
+| `notion_search` | Search pages and databases across a workspace |
+| `notion_list_databases` | List databases the integration has access to |
+| `notion_query_database` | Query a database with optional filters and sorts |
+| `notion_create_page` | Create a new page (in a database or as a child page) |
+| `notion_update_page` | Update page properties or archive/restore a page |
+| `notion_create_comment` | Add a comment to a page or discussion thread |
+| `notion_get_user` | Get user profile by ID or get the bot user |
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from matimo import Matimo
+from matimo_notion import get_tools_path
+
+async def main():
+    matimo = await Matimo.init(get_tools_path())
+
+    # Search for pages/databases
+    results = await matimo.execute('notion_search', {
+        'query': 'Product Roadmap',
+    })
+
+    # Query a database
+    rows = await matimo.execute('notion_query_database', {
+        'database_id': 'your-database-id',
+        'filter': {'property': 'Status', 'select': {'equals': 'In Progress'}},
+    })
+
+    # Create a page in a database
+    await matimo.execute('notion_create_page', {
+        'parent_id': 'your-database-id',
+        'title': 'New Task',
+        'properties': {'Status': {'select': {'name': 'Todo'}}},
+    })
+
+asyncio.run(main())
+```
+
+---
+
+## Authentication
+
+```bash
+export NOTION_API_KEY="secret_your-integration-token"
+```
+
+### Setting Up a Notion Integration
+
+1. Go to [notion.so/my-integrations](https://www.notion.so/my-integrations) → **New integration**
+2. Set capabilities: Read content, Update content, Insert content
+3. Copy the **Internal Integration Secret**
+4. Share the pages/databases you want to access with your integration
+
+---
+
+## Documentation
+
+- [Notion API Reference](https://developers.notion.com/reference)
+- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/native/notion)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-notion/
+- **GitHub:** https://github.com/tallclub/matimo
+- **Notion API Docs:** https://developers.notion.com/
+

matimo_notion-0.1.0/README.md

@@ -0,0 +1,92 @@
+# matimo-notion
+
+> Notion tools for [Matimo](https://matimo.dev) — create pages, query databases, search, and manage content.
+
+[![PyPI](https://img.shields.io/pypi/v/matimo-notion)](https://pypi.org/project/matimo-notion/)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+
+---
+
+## Installation
+
+```bash
+pip install matimo matimo-notion
+```
+
+---
+
+## Available Tools (7 Total)
+
+| Tool | Description |
+|------|-------------|
+| `notion_search` | Search pages and databases across a workspace |
+| `notion_list_databases` | List databases the integration has access to |
+| `notion_query_database` | Query a database with optional filters and sorts |
+| `notion_create_page` | Create a new page (in a database or as a child page) |
+| `notion_update_page` | Update page properties or archive/restore a page |
+| `notion_create_comment` | Add a comment to a page or discussion thread |
+| `notion_get_user` | Get user profile by ID or get the bot user |
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from matimo import Matimo
+from matimo_notion import get_tools_path
+
+async def main():
+    matimo = await Matimo.init(get_tools_path())
+
+    # Search for pages/databases
+    results = await matimo.execute('notion_search', {
+        'query': 'Product Roadmap',
+    })
+
+    # Query a database
+    rows = await matimo.execute('notion_query_database', {
+        'database_id': 'your-database-id',
+        'filter': {'property': 'Status', 'select': {'equals': 'In Progress'}},
+    })
+
+    # Create a page in a database
+    await matimo.execute('notion_create_page', {
+        'parent_id': 'your-database-id',
+        'title': 'New Task',
+        'properties': {'Status': {'select': {'name': 'Todo'}}},
+    })
+
+asyncio.run(main())
+```
+
+---
+
+## Authentication
+
+```bash
+export NOTION_API_KEY="secret_your-integration-token"
+```
+
+### Setting Up a Notion Integration
+
+1. Go to [notion.so/my-integrations](https://www.notion.so/my-integrations) → **New integration**
+2. Set capabilities: Read content, Update content, Insert content
+3. Copy the **Internal Integration Secret**
+4. Share the pages/databases you want to access with your integration
+
+---
+
+## Documentation
+
+- [Notion API Reference](https://developers.notion.com/reference)
+- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/native/notion)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-notion/
+- **GitHub:** https://github.com/tallclub/matimo
+- **Notion API Docs:** https://developers.notion.com/
+

matimo_notion-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "matimo-notion"
+version = "0.1.0"
+description = "Matimo provider — Notion tools (pages, databases, comments)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["ai", "tools", "agents", "matimo", "notion"]
+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"]
+notion = "matimo_notion:get_tools_path"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/matimo_notion"]

matimo_notion-0.1.0/src/matimo_notion/__init__.py

@@ -0,0 +1,17 @@
+"""Matimo notion 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 notion tool definitions."""
+    try:
+        ref = importlib.resources.files("matimo_notion") / "tools"
+        return str(ref)
+    except Exception:
+        return str(Path(__file__).parent / "tools")
+
+
+__all__ = ["get_tools_path"]

matimo_notion-0.1.0/src/matimo_notion/tools/notion_create_comment/definition.yaml

@@ -0,0 +1,97 @@
+name: notion_create_comment
+description: Add a comment to a Notion page, block, or discussion thread
+version: "1.0.0"
+parameters:
+  parent:
+    type: object
+    required: false
+    description: Parent target - provide one of page_id, block_id, or neither if using discussion_id
+  discussion_id:
+    type: string
+    required: false
+    description: The ID of existing discussion thread to respond to (alternative to parent)
+  rich_text:
+    type: array
+    required: true
+    description: Array of rich text objects representing comment content
+  attachments:
+    type: array
+    required: false
+    description: Array of file objects to attach to comment (max 3 allowed)
+  display_name:
+    type: object
+    required: false
+    description: Display name configuration for the comment author
+
+execution:
+  type: http
+  method: POST
+  url: "https://api.notion.com/v1/comments"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2022-06-28"
+    Content-Type: application/json
+  body:
+    parent: "{parent}"
+    discussion_id: "{discussion_id}"
+    rich_text: "{rich_text}"
+    attachments: "{attachments}"
+    display_name: "{display_name}"
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Ensure 'Insert comments' capability is enabled. Either page_id, block_id, or discussion_id required. Cannot start new inline discussions via API - must respond to existing threads or comment on pages/blocks."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    id:
+      type: string
+    created_time:
+      type: string
+    last_edited_time:
+      type: string
+    rich_text:
+      type: array
+    parent:
+      type: object
+  required: ["object", "id"]
+
+examples:
+  - name: "Comment on page with simple text"
+    params:
+      parent:
+        page_id: be633bf1-dfa0-436d-b259-571129a590e5
+      rich_text:
+        - type: text
+          text:
+            content: "This looks great! Consider adding more examples."
+    expected_result: "Comment posted on the page"
+  - name: "Reply to discussion thread"
+    params:
+      discussion_id: "discussion-thread-id"
+      rich_text:
+        - type: text
+          text:
+            content: "I agree with this suggestion"
+          annotations:
+            bold: true
+    expected_result: "Reply added to existing discussion thread"
+  - name: "Comment on block with attachment"
+    params:
+      parent:
+        block_id: block-id-uuid
+      rich_text:
+        - type: text
+          text:
+            content: "Attached document:"
+      attachments:
+        - url: https://example.com/document.pdf
+    expected_result: "Comment posted on block with file attachment"

matimo_notion-0.1.0/src/matimo_notion/tools/notion_create_page/definition.yaml

@@ -0,0 +1,127 @@
+name: notion_create_page
+description: Create a new page in a Notion database or as a child of an existing page
+version: "1.0.0"
+parameters:
+  parent:
+    type: object
+    required: true
+    description: |
+      Where to create the page. Provide ONE of:
+      - {"database_id": "..."}  to create in a database
+      - {"page_id": "..."}  to create as a sub-page
+      Get database_id from notion_list_databases.
+  properties:
+    type: object
+    required: false
+    description: |
+      Optional page properties (title, fields, etc).
+      Properties must match the parent database schema.
+      Simpler: just use 'markdown' parameter instead for content.
+  icon:
+    type: object
+    required: false
+    description: Page icon - object with type (emoji, external, file) and icon content
+  cover:
+    type: object
+    required: false
+    description: Page cover image - object with type (file, external) and image details
+  children:
+    type: array
+    required: false
+    description: Array of block objects to add to the page. Max 100 items
+  markdown:
+    type: string
+    required: false
+    description: |
+      Page content using Markdown syntax. Simple and works anywhere.
+      Example: "# My Title\n\nSome content here"
+      EASIEST WAY TO ADD CONTENT - use this instead of 'properties' for simplicity.
+  template:
+    type: object
+    required: false
+    description: Template to use for the page. Specify type and optional template_id
+  position:
+    type: object
+    required: false
+    description: Position of page in parent. Can specify before_id or after_id
+
+execution:
+  type: function
+  code: './index.py'
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Ensure 'Insert content' capability is enabled on the parent. Properties must match parent database schema. For database parents, properties are required. For page parents, only title is supported via properties. Either children or markdown can be used, not both. When using template, children parameter is not allowed."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    id:
+      type: string
+    created_time:
+      type: string
+    last_edited_time:
+      type: string
+    archived:
+      type: boolean
+    in_trash:
+      type: boolean
+    is_locked:
+      type: boolean
+    url:
+      type: string
+    public_url:
+      type: string
+    parent:
+      type: object
+    properties:
+      type: object
+    icon:
+      type: object
+    cover:
+      type: object
+  required: ["object", "id", "url"]
+
+examples:
+  - name: "Create page in database"
+    params:
+      parent:
+        database_id: a1d8501e-1ac1-43e9-a6bd-ea9fe6c8822b
+      properties:
+        Name:
+          title:
+            - text:
+                content: "New Page"
+    expected_result: "Creates a new page in the database with the specified properties"
+  - name: "Create page under existing page"
+    params:
+      parent:
+        page_id: be633bf1-dfa0-436d-b259-571129a590e5
+      children:
+        - object: block
+          type: paragraph
+          paragraph:
+            rich_text:
+              - type: text
+                text:
+                  content: "Page content"
+    expected_result: "Creates a subpage with content blocks"
+  - name: "Create page with emoji icon"
+    params:
+      parent:
+        database_id: a1d8501e-1ac1-43e9-a6bd-ea9fe6c8822b
+      properties:
+        Name:
+          title:
+            - text:
+                content: "Task"
+      icon:
+        type: emoji
+        emoji: "✅"
+    expected_result: "Creates a page with an emoji icon"

matimo_notion-0.1.0/src/matimo_notion/tools/notion_create_page/index.py

@@ -0,0 +1,169 @@
+"""
+notion_create_page — Creates a new page in a Notion database or as a child page.
+Mirrors: typescript/packages/notion/tools/notion_create_page/index.ts
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+import httpx
+
+from matimo.errors import ErrorCode, MatimoError
+
+_NOTION_VERSION = "2022-06-28"
+_NOTION_PAGES_URL = "https://api.notion.com/v1/pages"
+_NOTION_DATABASES_URL = "https://api.notion.com/v1/databases"
+
+
+def _markdown_to_children(md: str) -> list[dict]:
+    """Convert markdown text to Notion block children (headings + paragraphs)."""
+    blocks: list[dict] = []
+    for part in re.split(r"\n\n+", md):
+        part = part.strip()
+        if not part:
+            continue
+        if part.startswith("### "):
+            blocks.append({
+                "object": "block", "type": "heading_3",
+                "heading_3": {"rich_text": [{"type": "text", "text": {"content": part[4:]}}]},
+            })
+        elif part.startswith("## "):
+            blocks.append({
+                "object": "block", "type": "heading_2",
+                "heading_2": {"rich_text": [{"type": "text", "text": {"content": part[3:]}}]},
+            })
+        elif part.startswith("# "):
+            blocks.append({
+                "object": "block", "type": "heading_1",
+                "heading_1": {"rich_text": [{"type": "text", "text": {"content": part[2:]}}]},
+            })
+        else:
+            blocks.append({
+                "object": "block", "type": "paragraph",
+                "paragraph": {"rich_text": [{"type": "text", "text": {"content": part}}]},
+            })
+    return blocks
+
+
+async def run(params: dict[str, Any]) -> dict[str, Any]:
+    api_key = os.environ.get("NOTION_API_KEY")
+    if not api_key:
+        raise MatimoError(
+            "NOTION_API_KEY not set",
+            ErrorCode.AUTH_FAILED,
+            {"env_var": "NOTION_API_KEY"},
+        )
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Notion-Version": _NOTION_VERSION,
+        "Content-Type": "application/json",
+    }
+
+    parent: dict | None = params.get("parent")
+    properties: dict | None = params.get("properties")
+    icon: dict | None = params.get("icon")
+    cover: dict | None = params.get("cover")
+    children: list | None = params.get("children")
+    markdown: str | None = params.get("markdown")
+    template: dict | None = params.get("template")
+    position: dict | None = params.get("position")
+
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        # Auto-discover a database if parent not provided
+        if not parent:
+            resp = await client.get(_NOTION_DATABASES_URL, headers=headers, params={"page_size": 1})
+            if resp.status_code != 200:
+                raise MatimoError(
+                    f"Failed to auto-discover database: {resp.text}",
+                    ErrorCode.EXECUTION_FAILED,
+                )
+            databases = resp.json().get("results", [])
+            if not databases:
+                raise MatimoError(
+                    "No databases found in workspace. Create a database first or provide `parent` parameter.",
+                    ErrorCode.EXECUTION_FAILED,
+                )
+            parent = {"database_id": databases[0]["id"]}
+
+        # Validate: children and markdown are mutually exclusive
+        has_children = isinstance(children, list) and len(children) > 0
+        has_markdown = isinstance(markdown, str) and markdown.strip()
+
+        if has_children and has_markdown:
+            raise MatimoError(
+                "Provide either `children` or `markdown`, not both",
+                ErrorCode.VALIDATION_FAILED,
+                {"children": len(children), "markdown": len(markdown)},
+            )
+
+        if template and has_children:
+            raise MatimoError(
+                "`template` cannot be used together with `children`.",
+                ErrorCode.VALIDATION_FAILED,
+            )
+
+        # Convert markdown → children if needed
+        if not has_children and has_markdown:
+            children = _markdown_to_children(markdown)
+
+        is_database_parent = isinstance(parent, dict) and "database_id" in parent
+
+        # Build base request body
+        body: dict[str, Any] = {"parent": parent}
+        if properties:
+            body["properties"] = properties
+        if icon:
+            body["icon"] = icon
+        if cover:
+            body["cover"] = cover
+        if children:
+            body["children"] = children
+        if template:
+            body["template"] = template
+        if position:
+            body["position"] = position
+
+        # When creating in a database without explicit properties, try common title field names
+        title_candidates = None
+        if is_database_parent and not properties and has_markdown:
+            first_line = re.sub(r"^#+\s*", "", markdown.split("\n")[0]).strip() or "New Page"
+            title_candidates = ["Name", "Title", "title", "name"]
+
+        if title_candidates:
+            last_error: dict | None = None
+            for candidate in title_candidates:
+                candidate_props = {
+                    candidate: {"title": [{"text": {"content": first_line}}]}
+                }
+                try_body = {**body, "properties": candidate_props}
+                resp = await client.post(_NOTION_PAGES_URL, headers=headers, json=try_body)
+                if resp.status_code == 200:
+                    return {"success": True, "status_code": resp.status_code, "data": resp.json()}
+                err_data = resp.json()
+                msg = err_data.get("message", "")
+                if "is not a property that exists" in msg:
+                    last_error = err_data
+                    continue
+                # Non-recoverable error
+                return {"success": False, "status_code": resp.status_code, "error": err_data}
+
+            return {"success": False, "status_code": 0, "error": last_error or "All title candidates failed"}
+
+        # Single request
+        resp = await client.post(_NOTION_PAGES_URL, headers=headers, json=body)
+        if resp.status_code == 200:
+            return {"success": True, "status_code": resp.status_code, "data": resp.json()}
+
+        err_data = resp.json()
+        raise MatimoError(
+            err_data.get("message", "Notion API error"),
+            ErrorCode.EXECUTION_FAILED,
+            {
+                "status": resp.status_code,
+                "code": err_data.get("code"),
+                "request_id": err_data.get("request_id"),
+            },
+        )

matimo_notion-0.1.0/src/matimo_notion/tools/notion_get_user/definition.yaml

@@ -0,0 +1,55 @@
+name: notion_get_user
+description: Retrieve information about a Notion user
+version: "1.0.0"
+parameters:
+  user_id:
+    type: string
+    required: true
+    description: The UUID of the user to retrieve
+
+execution:
+  type: http
+  method: GET
+  url: "https://api.notion.com/v1/users/{user_id}"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2022-06-28"
+  timeout: 10000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Ensure 'Read user information' capability is enabled. Returns user details including name, avatar, email (if available). User IDs can be obtained from page.created_by, page.last_edited_by, or database results."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    id:
+      type: string
+    type:
+      type: string
+    name:
+      type: string
+    avatar_url:
+      type: string
+    person:
+      type: object
+      properties:
+        email:
+          type: string
+  required: ["object", "id", "type"]
+
+examples:
+  - name: "Get user information"
+    params:
+      user_id: "e79a0b74-3aba-4149-9f74-0bb5791a6ee6"
+    expected_result: "Returns user details with name, avatar, email"
+  - name: "Get bot user info"
+    params:
+      user_id: "c2f20311-9e54-4d11-8c79-7398424ae41e"
+    expected_result: "Returns bot/integration user information"

matimo_notion-0.1.0/src/matimo_notion/tools/notion_list_databases/definition.yaml

@@ -0,0 +1,70 @@
+name: notion_list_databases
+description: |
+  List all databases (data sources) available in your Notion workspace.
+  Use this to discover what databases exist before querying them.
+  Each database has an id, title, icon, and URL that you can use for further operations.
+version: "1.0.0"
+
+parameters:
+  page_size:
+    type: number
+    required: false
+    description: How many databases to return (1-100). Omit to use Notion's default (up to 100).
+
+execution:
+  type: http
+  method: POST
+  url: "https://api.notion.com/v1/search"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2022-06-28"
+    Content-Type: application/json
+  body:
+    filter:
+      property: object
+      value: database
+    page_size: "{page_size}"
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Lists only databases shared with your integration. Respects integration's read capabilities."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    results:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+          title:
+            type: array
+          icon:
+            type: object
+          url:
+            type: string
+    has_more:
+      type: boolean
+    next_cursor:
+      anyOf:
+        - type: string
+        - type: "null"
+
+examples:
+  - name: "List all databases in workspace"
+    params:
+      page_size: 10
+    expected_result: "Returns array of database objects with id, title, icon, and url"
+  - name: "List first database only"
+    params:
+      page_size: 1
+    expected_result: "Returns single database object"

matimo_notion-0.1.0/src/matimo_notion/tools/notion_query_database/definition.yaml

@@ -0,0 +1,102 @@
+name: notion_query_database
+description: Query pages from a Notion database to retrieve content. Use notion_list_databases first to get the database ID.
+version: "1.0.0"
+parameters:
+  database_id:
+    type: string
+    required: true
+    description: The ID of the database to query. Get from notion_list_databases (item.id)
+  sorts:
+    type: array
+    required: false
+    description: Array of sort objects to order results by properties or timestamps
+  filter:
+    type: object
+    required: false
+    description: Filter criteria as JSON object to narrow results
+  page_size:
+    type: number
+    required: false
+    description: Number of results per request (default 100, max 100)
+  start_cursor:
+    type: string
+    required: false
+    description: Cursor for pagination to retrieve next set of results
+  archived:
+    type: boolean
+    required: false
+    description: If true, include archived pages in results
+  in_trash:
+    type: boolean
+    required: false
+    description: If true, include pages in trash in results
+  result_type:
+    type: string
+    required: false
+    description: Filter results by type - page or data_source (for wikis only)
+
+execution:
+  type: http
+  method: POST
+  url: "https://api.notion.com/v1/databases/{database_id}/query"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2022-06-28"
+    Content-Type: application/json
+  body:
+    sorts: "{sorts}"
+    filter: "{filter}"
+    page_size: "{page_size}"
+    start_cursor: "{start_cursor}"
+    archived: "{archived}"
+    in_trash: "{in_trash}"
+    result_type: "{result_type}"
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  api_version: "2022-06-28"
+  caution: "Uses current Notion API (2022-06-28). Ensure 'Read content' capability is enabled on the integration. Filter and sort are optional - omit if not needed. API returns max 100 items per call."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    type:
+      type: string
+    results:
+      type: array
+    has_more:
+      type: boolean
+    next_cursor:
+      anyOf:
+        - type: string
+        - type: "null"
+  required: ["object", "results", "has_more"]
+
+examples:
+  - name: "Query data source - all pages"
+    params:
+      database_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
+    expected_result: "Returns paginated list of all pages in the database"
+  - name: "Query data source - with filter"
+    params:
+      database_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
+      filter:
+        property: Status
+        status:
+          equals: Done
+    expected_result: "Returns pages where the Status property equals 'Done'"
+  - name: "Query data source - with sorting"
+    params:
+      database_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
+      sorts:
+        - property: Created
+          direction: descending
+      page_size: 25
+    expected_result: "Returns up to 25 pages sorted by creation date (descending)"

matimo_notion-0.1.0/src/matimo_notion/tools/notion_search/definition.yaml

@@ -0,0 +1,89 @@
+name: notion_search
+description: Search across all pages and data sources in Notion workspace by title
+version: "1.0.0"
+parameters:
+  query:
+    type: string
+    required: false
+    description: Search text to find in page/data_source titles - omit to return all shared items
+  filter_object:
+    type: object
+    required: false
+    description: Filter results by object type - page or data_source
+  sort_direction:
+    type: string
+    required: false
+    description: Sort direction - ascending or descending
+  sort_timestamp:
+    type: string
+    required: false
+    description: Sort by timestamp - last_edited_time (default) or created_time
+  page_size:
+    type: number
+    required: false
+    description: Number of results per request
+  start_cursor:
+    type: string
+    required: false
+    description: Cursor for pagination to retrieve next set of results
+
+execution:
+  type: http
+  method: POST
+  url: "https://api.notion.com/v1/search"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2022-06-28"
+    Content-Type: application/json
+  body:
+    query: "{query}"
+    filter: "{filter_object}"
+    sort:
+      direction: "{sort_direction}"
+      timestamp: "{sort_timestamp}"
+    page_size: "{page_size}"
+    start_cursor: "{start_cursor}"
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Omit 'query' parameter to return all pages/data sources shared with integration. Filter and sort are optional. Results respect integration's read capabilities. API version 2022-06-28."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    type:
+      type: string
+    page_or_data_source:
+      type: object
+    results:
+      type: array
+    has_more:
+      type: boolean
+    next_cursor:
+      anyOf:
+        - type: string
+        - type: "null"
+  required: ["object", "type", "results", "has_more"]
+
+examples:
+  - name: "Search for pages by title"
+    params:
+      query: "meeting notes"
+    expected_result: "Returns all pages with 'meeting notes' in title"
+  - name: "Search data sources only"
+    params:
+      filter_object: "data_source"
+      sort_timestamp: "last_edited_time"
+      sort_direction: "descending"
+    expected_result: "Returns recently edited data sources only"
+  - name: "Get all shared items"
+    params:
+      page_size: 50
+    expected_result: "Returns first 50 pages and data sources shared with integration"

matimo_notion-0.1.0/src/matimo_notion/tools/notion_update_page/definition.yaml

@@ -0,0 +1,117 @@
+name: notion_update_page
+description: Update properties, icon, cover, or other attributes of an existing Notion page
+version: "1.0.0"
+parameters:
+  page_id:
+    type: string
+    required: true
+    description: The ID of the page to update (UUID format, dashes optional)
+  properties:
+    type: object
+    required: false
+    description: Page properties to update as JSON object - must match parent data source schema
+  icon:
+    type: object
+    required: false
+    description: Page icon object with type and content (emoji, external URL, or file)
+  cover:
+    type: object
+    required: false
+    description: Page cover image object with type and file/external URL details
+  is_locked:
+    type: boolean
+    required: false
+    description: Whether to lock page from editing in Notion UI
+  template:
+    type: object
+    required: false
+    description: Template object to apply - type default or template_id with specific template ID
+  erase_content:
+    type: boolean
+    required: false
+    description: Whether to erase all existing page content (use with template to replace content)
+  archived:
+    type: boolean
+    required: false
+    description: Whether to archive or restore the page
+  in_trash:
+    type: boolean
+    required: false
+    description: Whether to move page to trash or restore it
+
+execution:
+  type: http
+  method: PATCH
+  url: "https://api.notion.com/v1/pages/{page_id}"
+  headers:
+    Authorization: "Bearer {NOTION_API_KEY}"
+    "Notion-Version": "2022-06-28"
+    Content-Type: application/json
+  body:
+    properties: "{properties}"
+    icon: "{icon}"
+    cover: "{cover}"
+    is_locked: "{is_locked}"
+    template: "{template}"
+    erase_content: "{erase_content}"
+    archived: "{archived}"
+    in_trash: "{in_trash}"
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  name: Authorization
+notes:
+  env: NOTION_API_KEY
+  caution: "Ensure 'Update content' capability is enabled. Only include parameters you want to change. Cannot update parent, created_by, created_time, last_edited_by, last_edited_time, or rollup properties via API."
+
+output_schema:
+  type: object
+  properties:
+    object:
+      type: string
+    id:
+      type: string
+    created_time:
+      type: string
+    last_edited_time:
+      type: string
+    archived:
+      type: boolean
+    in_trash:
+      type: boolean
+    is_locked:
+      type: boolean
+    properties:
+      type: object
+  required: ["object", "id", "last_edited_time"]
+
+examples:
+  - name: "Update page title"
+    params:
+      page_id: "be633bf1-dfa0-436d-b259-571129a590e5"
+      properties:
+        Name:
+          title:
+            - text:
+                content: Updated Title
+    expected_result: "Page title updated to 'Updated Title'"
+  - name: "Update page icon"
+    params:
+      page_id: "be633bf1-dfa0-436d-b259-571129a590e5"
+      icon:
+        type: emoji
+        emoji: "🎉"
+    expected_result: "Page icon changed to celebration emoji"
+  - name: "Update page with cover and apply template"
+    params:
+      page_id: "be633bf1-dfa0-436d-b259-571129a590e5"
+      cover:
+        type: external
+        external:
+          url: https://example.com/image.png
+      template:
+        type: default
+      erase_content: true
+    expected_result: "Page cover set, default template applied, existing content replaced"