ldraney-notion-mcp 0.1.2__tar.gz → 0.1.4__tar.gz

{ldraney_notion_mcp-0.1.2 → ldraney_notion_mcp-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ldraney-notion-mcp
-Version: 0.1.2
+Version: 0.1.4
 Summary: MCP server wrapping the Notion Python SDK (v2025-09-03)
 License: MIT
 Requires-Python: >=3.10

{ldraney_notion_mcp-0.1.2 → ldraney_notion_mcp-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ldraney-notion-mcp"
-version = "0.1.2"
+version = "0.1.4"
 description = "MCP server wrapping the Notion Python SDK (v2025-09-03)"
 readme = "README.md"
 requires-python = ">=3.10"

{ldraney_notion_mcp-0.1.2 → ldraney_notion_mcp-0.1.4}/src/ldraney_notion_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ldraney-notion-mcp
-Version: 0.1.2
+Version: 0.1.4
 Summary: MCP server wrapping the Notion Python SDK (v2025-09-03)
 License: MIT
 Requires-Python: >=3.10

{ldraney_notion_mcp-0.1.2 → ldraney_notion_mcp-0.1.4}/src/notion_mcp/tools/blocks.py

@@ -3,13 +3,17 @@
 from __future__ import annotations
 
 import json
-from typing import Any
+from typing import Annotated, Any
+
+from pydantic import Field
 
 from ..server import mcp, get_client, _parse_json, _error_response
 
 
 @mcp.tool()
-def get_block(block_id: str) -> str:
+def get_block(
+    block_id: Annotated[str, Field(description="The UUID of the block to retrieve")],
+) -> str:
     """Retrieve a Notion block by its ID.
 
     Args:
@@ -24,9 +28,9 @@ def get_block(block_id: str) -> str:
 
 @mcp.tool()
 def get_block_children(
-    block_id: str,
-    start_cursor: str | None = None,
-    page_size: int | None = None,
+    block_id: Annotated[str, Field(description="The UUID of the parent block")],
+    start_cursor: Annotated[str | None, Field(description="Cursor for pagination")] = None,
+    page_size: Annotated[int | None, Field(description="Number of results per page")] = None,
 ) -> str:
     """List child blocks of a Notion block.
 
@@ -47,9 +51,14 @@ def get_block_children(
 
 
 @mcp.tool()
-def append_block_children(block_id: str, children: str) -> str:
+def append_block_children(
+    block_id: Annotated[str, Field(description="The UUID of the parent block to append children to")],
+    children: Annotated[str, Field(description="JSON string for a list of block objects to append, e.g. '[{\"object\": \"block\", \"type\": \"paragraph\", \"paragraph\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"Hello\"}}]}}]'")],
+) -> str:
     """Append child blocks to a Notion block.
 
+    IMPORTANT: The children parameter must be passed as a JSON-encoded string, NOT as an object.
+
     Args:
         block_id: The UUID of the parent block to append children to.
         children: JSON string for a list of block objects to append.
@@ -66,15 +75,17 @@ def append_block_children(block_id: str, children: str) -> str:
 
 @mcp.tool()
 def update_block(
-    block_id: str,
-    content: str | None = None,
+    block_id: Annotated[str, Field(description="The UUID of the block to update")],
+    content: Annotated[str | None, Field(description="JSON string of block properties to update. The keys depend on the block type, e.g. '{\"paragraph\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"Updated text\"}}]}}'")] = None,
 ) -> str:
     """Update a Notion block.
 
+    IMPORTANT: The content parameter must be passed as a JSON-encoded string, NOT as an object.
+
     Args:
         block_id: The UUID of the block to update.
         content: JSON string of block properties to update. The keys depend
-            on the block type (e.g. {"paragraph": {"rich_text": [...]}}).
+            on the block type (e.g. '{"paragraph": {"rich_text": [...]}}').
     """
     try:
         kwargs: dict[str, Any] = {}
@@ -87,7 +98,9 @@ def update_block(
 
 
 @mcp.tool()
-def delete_block(block_id: str) -> str:
+def delete_block(
+    block_id: Annotated[str, Field(description="The UUID of the block to delete")],
+) -> str:
     """Delete (archive) a Notion block.
 
     Args:

{ldraney_notion_mcp-0.1.2 → ldraney_notion_mcp-0.1.4}/src/notion_mcp/tools/comments.py

@@ -3,23 +3,28 @@
 from __future__ import annotations
 
 import json
+from typing import Annotated
+
+from pydantic import Field
 
 from ..server import mcp, get_client, _parse_json, _error_response
 
 
 @mcp.tool()
 def create_comment(
-    parent: str,
-    rich_text: str,
-    discussion_id: str | None = None,
+    parent: Annotated[str, Field(description="JSON string for the parent object, e.g. '{\"page_id\": \"...\"}'")],
+    rich_text: Annotated[str, Field(description="JSON string for the rich-text content array, e.g. '[{\"type\": \"text\", \"text\": {\"content\": \"Hello!\"}}]'")],
+    discussion_id: Annotated[str | None, Field(description="UUID of an existing discussion thread to reply to. Omit to start a new top-level comment.")] = None,
 ) -> str:
     """Create a comment on a Notion page or block.
 
+    IMPORTANT: parent and rich_text must be passed as JSON-encoded strings, NOT as objects.
+
     Args:
         parent: JSON string for the parent object,
-            e.g. {"page_id": "..."}.
+            e.g. '{"page_id": "..."}'.
         rich_text: JSON string for the rich-text content array,
-            e.g. [{"type": "text", "text": {"content": "Hello!"}}].
+            e.g. '[{"type": "text", "text": {"content": "Hello!"}}]'.
         discussion_id: Optional UUID of an existing discussion thread
             to reply to. Omit to start a new top-level comment.
     """
@@ -39,9 +44,9 @@ def create_comment(
 
 @mcp.tool()
 def get_comments(
-    block_id: str,
-    start_cursor: str | None = None,
-    page_size: int | None = None,
+    block_id: Annotated[str, Field(description="The UUID of the block or page to list comments for")],
+    start_cursor: Annotated[str | None, Field(description="Cursor for pagination")] = None,
+    page_size: Annotated[int | None, Field(description="Number of results per page")] = None,
 ) -> str:
     """List comments on a Notion block or page.
 

{ldraney_notion_mcp-0.1.2 → ldraney_notion_mcp-0.1.4}/src/notion_mcp/tools/databases.py

@@ -3,7 +3,9 @@
 from __future__ import annotations
 
 import json
-from typing import Any
+from typing import Annotated, Any
+
+from pydantic import Field
 
 from ..server import mcp, get_client, _parse_json, _error_response
 
@@ -15,19 +17,21 @@ from ..server import mcp, get_client, _parse_json, _error_response
 
 @mcp.tool()
 def create_database(
-    parent: str,
-    title: str,
-    initial_data_source: str | None = None,
+    parent: Annotated[str, Field(description="JSON string for the parent object, e.g. '{\"type\": \"page_id\", \"page_id\": \"...\"}'")],
+    title: Annotated[str, Field(description="JSON string for the title rich-text array, e.g. '[{\"type\": \"text\", \"text\": {\"content\": \"My DB\"}}]'")],
+    initial_data_source: Annotated[str | None, Field(description="JSON string for the initial data source configuration including properties")] = None,
 ) -> str:
     """Create a new Notion database.
 
     In Notion API v2025-09-03, database properties live on data sources.
     Pass properties inside initial_data_source.properties.
 
+    IMPORTANT: All structured parameters must be passed as JSON-encoded strings, NOT as objects.
+
     Args:
-        parent: JSON string for the parent object, e.g. {"type": "page_id", "page_id": "..."}.
+        parent: JSON string for the parent object, e.g. '{"type": "page_id", "page_id": "..."}'.
         title: JSON string for the title rich-text array,
-            e.g. [{"type": "text", "text": {"content": "My DB"}}].
+            e.g. '[{"type": "text", "text": {"content": "My DB"}}]'.
         initial_data_source: Optional JSON string for the initial data source
             configuration including properties.
     """
@@ -43,7 +47,9 @@ def create_database(
 
 
 @mcp.tool()
-def get_database(database_id: str) -> str:
+def get_database(
+    database_id: Annotated[str, Field(description="The UUID of the database to retrieve")],
+) -> str:
     """Retrieve a Notion database by its ID.
 
     Note: In v2025-09-03 the response contains data_sources but NOT
@@ -61,14 +67,16 @@ def get_database(database_id: str) -> str:
 
 @mcp.tool()
 def update_database(
-    database_id: str,
-    title: str | None = None,
-    description: str | None = None,
-    icon: str | None = None,
-    cover: str | None = None,
+    database_id: Annotated[str, Field(description="The UUID of the database to update")],
+    title: Annotated[str | None, Field(description="JSON string for the new title rich-text array, e.g. '[{\"type\": \"text\", \"text\": {\"content\": \"New Title\"}}]'")] = None,
+    description: Annotated[str | None, Field(description="JSON string for the description rich-text array, e.g. '[{\"type\": \"text\", \"text\": {\"content\": \"A description\"}}]'")] = None,
+    icon: Annotated[str | None, Field(description="JSON string for the database icon, e.g. '{\"type\": \"emoji\", \"emoji\": \"📊\"}'")] = None,
+    cover: Annotated[str | None, Field(description="JSON string for the database cover, e.g. '{\"type\": \"external\", \"external\": {\"url\": \"https://...\"}}'")] = None,
 ) -> str:
     """Update a Notion database.
 
+    IMPORTANT: All structured parameters must be passed as JSON-encoded strings, NOT as objects.
+
     Args:
         database_id: The UUID of the database to update.
         title: Optional JSON string for the new title rich-text array.
@@ -93,7 +101,9 @@ def update_database(
 
 
 @mcp.tool()
-def archive_database(database_id: str) -> str:
+def archive_database(
+    database_id: Annotated[str, Field(description="The UUID of the database to archive")],
+) -> str:
     """Archive a Notion database.
 
     Args:
@@ -108,17 +118,19 @@ def archive_database(database_id: str) -> str:
 
 @mcp.tool()
 def query_database(
-    database_id: str,
-    filter: str | None = None,
-    sorts: str | None = None,
-    start_cursor: str | None = None,
-    page_size: int | None = None,
+    database_id: Annotated[str, Field(description="The UUID of the database to query")],
+    filter: Annotated[str | None, Field(description="JSON string for a filter object, e.g. '{\"property\": \"Status\", \"select\": {\"equals\": \"Done\"}}'")] = None,
+    sorts: Annotated[str | None, Field(description="JSON string for a list of sort objects, e.g. '[{\"property\": \"Created\", \"direction\": \"descending\"}]'")] = None,
+    start_cursor: Annotated[str | None, Field(description="Cursor for pagination")] = None,
+    page_size: Annotated[int | None, Field(description="Number of results per page")] = None,
 ) -> str:
     """Query a Notion database for pages/rows.
 
     Automatically resolves the first data source and queries it.
     If you already know the data source ID, use query_data_source instead.
 
+    IMPORTANT: filter and sorts must be passed as JSON-encoded strings, NOT as objects.
+
     Args:
         database_id: The UUID of the database to query.
         filter: Optional JSON string for a filter object.
@@ -145,7 +157,9 @@ def query_database(
 
 
 @mcp.tool()
-def get_data_source(data_source_id: str) -> str:
+def get_data_source(
+    data_source_id: Annotated[str, Field(description="The UUID of the data source to retrieve")],
+) -> str:
     """Retrieve a Notion data source (includes properties).
 
     Args:
@@ -160,11 +174,13 @@ def get_data_source(data_source_id: str) -> str:
 
 @mcp.tool()
 def update_data_source(
-    data_source_id: str,
-    properties: str | None = None,
+    data_source_id: Annotated[str, Field(description="The UUID of the data source to update")],
+    properties: Annotated[str | None, Field(description="JSON string for properties to update, e.g. '{\"Name\": {\"title\": {}}, \"Tags\": {\"multi_select\": {}}}'")] = None,
 ) -> str:
     """Update a Notion data source.
 
+    IMPORTANT: The properties parameter must be passed as a JSON-encoded string, NOT as an object.
+
     Args:
         data_source_id: The UUID of the data source to update.
         properties: Optional JSON string for properties to update.
@@ -181,14 +197,16 @@ def update_data_source(
 
 @mcp.tool()
 def query_data_source(
-    data_source_id: str,
-    filter: str | None = None,
-    sorts: str | None = None,
-    start_cursor: str | None = None,
-    page_size: int | None = None,
+    data_source_id: Annotated[str, Field(description="The UUID of the data source to query")],
+    filter: Annotated[str | None, Field(description="JSON string for a filter object, e.g. '{\"property\": \"Status\", \"select\": {\"equals\": \"Done\"}}'")] = None,
+    sorts: Annotated[str | None, Field(description="JSON string for a list of sort objects, e.g. '[{\"property\": \"Created\", \"direction\": \"descending\"}]'")] = None,
+    start_cursor: Annotated[str | None, Field(description="Cursor for pagination")] = None,
+    page_size: Annotated[int | None, Field(description="Number of results per page")] = None,
 ) -> str:
     """Query rows in a Notion data source.
 
+    IMPORTANT: filter and sorts must be passed as JSON-encoded strings, NOT as objects.
+
     Args:
         data_source_id: The UUID of the data source to query.
         filter: Optional JSON string for a filter object.
@@ -211,10 +229,10 @@ def query_data_source(
 
 @mcp.tool()
 def list_data_source_templates(
-    data_source_id: str,
-    name: str | None = None,
-    start_cursor: str | None = None,
-    page_size: int | None = None,
+    data_source_id: Annotated[str, Field(description="The UUID of the data source")],
+    name: Annotated[str | None, Field(description="Name filter for templates")] = None,
+    start_cursor: Annotated[str | None, Field(description="Cursor for pagination")] = None,
+    page_size: Annotated[int | None, Field(description="Number of results per page")] = None,
 ) -> str:
     """List templates for a Notion data source.
 

{ldraney_notion_mcp-0.1.2 → ldraney_notion_mcp-0.1.4}/src/notion_mcp/tools/pages.py

@@ -3,28 +3,32 @@
 from __future__ import annotations
 
 import json
-from typing import Any
+from typing import Annotated, Any
+
+from pydantic import Field
 
 from ..server import mcp, get_client, _parse_json, _error_response
 
 
 @mcp.tool()
 def create_page(
-    parent: str,
-    properties: str,
-    children: str | None = None,
-    template: str | None = None,
+    parent: Annotated[str, Field(description="JSON string for the parent object, e.g. '{\"type\": \"page_id\", \"page_id\": \"...\"}'")],
+    properties: Annotated[str, Field(description="JSON string for the page properties mapping, e.g. '{\"title\": [{\"text\": {\"content\": \"My Page\"}}]}'")],
+    children: Annotated[str | None, Field(description="JSON string for a list of block children to append. Cannot be used together with template.")] = None,
+    template: Annotated[str | None, Field(description="JSON string for a data-source template, e.g. '{\"type\": \"none\"}', '{\"type\": \"default\"}', or '{\"type\": \"template_id\", \"template_id\": \"<uuid>\"}'")] = None,
 ) -> str:
     """Create a new Notion page.
 
+    IMPORTANT: All structured parameters must be passed as JSON-encoded strings, NOT as objects.
+
     Args:
-        parent: JSON string for the parent object, e.g. {"type": "page_id", "page_id": "..."}.
+        parent: JSON string for the parent object, e.g. '{"type": "page_id", "page_id": "..."}'.
         properties: JSON string for the page properties mapping.
         children: Optional JSON string for a list of block children to append.
             Cannot be used together with template.
         template: Optional JSON string for a data-source template, e.g.
-            {"type": "none"}, {"type": "default"}, or
-            {"type": "template_id", "template_id": "<uuid>"}.
+            '{"type": "none"}', '{"type": "default"}', or
+            '{"type": "template_id", "template_id": "<uuid>"}'.
     """
     try:
         result = get_client().create_page(
@@ -39,7 +43,9 @@ def create_page(
 
 
 @mcp.tool()
-def get_page(page_id: str) -> str:
+def get_page(
+    page_id: Annotated[str, Field(description="The UUID of the page to retrieve")],
+) -> str:
     """Retrieve a Notion page by its ID.
 
     Args:
@@ -54,14 +60,16 @@ def get_page(page_id: str) -> str:
 
 @mcp.tool()
 def update_page(
-    page_id: str,
-    properties: str | None = None,
-    erase_content: bool | None = None,
-    icon: str | None = None,
-    cover: str | None = None,
+    page_id: Annotated[str, Field(description="The UUID of the page to update")],
+    properties: Annotated[str | None, Field(description="JSON string of properties to update, e.g. '{\"Name\": {\"title\": [{\"text\": {\"content\": \"New Title\"}}]}}'")] = None,
+    erase_content: Annotated[bool | None, Field(description="If true, clears ALL block content from the page. WARNING: This is destructive and irreversible.")] = None,
+    icon: Annotated[str | None, Field(description="JSON string for the page icon, e.g. '{\"type\": \"emoji\", \"emoji\": \"🎉\"}'")] = None,
+    cover: Annotated[str | None, Field(description="JSON string for the page cover, e.g. '{\"type\": \"external\", \"external\": {\"url\": \"https://...\"}}'")] = None,
 ) -> str:
     """Update a Notion page's properties, icon, or cover.
 
+    IMPORTANT: All structured parameters must be passed as JSON-encoded strings, NOT as objects.
+
     Args:
         page_id: The UUID of the page to update.
         properties: Optional JSON string of properties to update.
@@ -89,7 +97,9 @@ def update_page(
 
 
 @mcp.tool()
-def archive_page(page_id: str) -> str:
+def archive_page(
+    page_id: Annotated[str, Field(description="The UUID of the page to archive")],
+) -> str:
     """Archive (soft-delete) a Notion page.
 
     Args:
@@ -103,13 +113,18 @@ def archive_page(page_id: str) -> str:
 
 
 @mcp.tool()
-def move_page(page_id: str, parent: str) -> str:
+def move_page(
+    page_id: Annotated[str, Field(description="The UUID of the page to move")],
+    parent: Annotated[str, Field(description="JSON string for the new parent object, e.g. '{\"type\": \"page_id\", \"page_id\": \"...\"}'")],
+) -> str:
     """Move a Notion page to a new parent.
 
+    IMPORTANT: The parent parameter must be passed as a JSON-encoded string, NOT as an object.
+
     Args:
         page_id: The UUID of the page to move.
         parent: JSON string for the new parent object,
-            e.g. {"type": "page_id", "page_id": "..."}.
+            e.g. '{"type": "page_id", "page_id": "..."}'.
     """
     try:
         result = get_client().move_page(

{ldraney_notion_mcp-0.1.2 → ldraney_notion_mcp-0.1.4}/src/notion_mcp/tools/search.py

@@ -3,26 +3,31 @@
 from __future__ import annotations
 
 import json
+from typing import Annotated
+
+from pydantic import Field
 
 from ..server import mcp, get_client, _parse_json, _error_response
 
 
 @mcp.tool()
 def search(
-    query: str | None = None,
-    filter: str | None = None,
-    sort: str | None = None,
-    start_cursor: str | None = None,
-    page_size: int | None = None,
+    query: Annotated[str | None, Field(description="Text query to search for")] = None,
+    filter: Annotated[str | None, Field(description="JSON string for a filter object, e.g. '{\"value\": \"page\", \"property\": \"object\"}'")] = None,
+    sort: Annotated[str | None, Field(description="JSON string for a sort object, e.g. '{\"direction\": \"ascending\", \"timestamp\": \"last_edited_time\"}'")] = None,
+    start_cursor: Annotated[str | None, Field(description="Cursor for pagination")] = None,
+    page_size: Annotated[int | None, Field(description="Number of results per page")] = None,
 ) -> str:
     """Search Notion pages and databases.
 
+    IMPORTANT: filter and sort must be passed as JSON-encoded strings, NOT as objects.
+
     Args:
         query: Optional text query to search for.
         filter: Optional JSON string for a filter object,
-            e.g. {"value": "page", "property": "object"}.
+            e.g. '{"value": "page", "property": "object"}'.
         sort: Optional JSON string for a sort object,
-            e.g. {"direction": "ascending", "timestamp": "last_edited_time"}.
+            e.g. '{"direction": "ascending", "timestamp": "last_edited_time"}'.
         start_cursor: Optional cursor for pagination.
         page_size: Optional number of results per page.
     """

{ldraney_notion_mcp-0.1.2 → ldraney_notion_mcp-0.1.4}/src/notion_mcp/tools/users.py

@@ -3,14 +3,17 @@
 from __future__ import annotations
 
 import json
+from typing import Annotated
+
+from pydantic import Field
 
 from ..server import mcp, get_client, _error_response
 
 
 @mcp.tool()
 def get_users(
-    start_cursor: str | None = None,
-    page_size: int | None = None,
+    start_cursor: Annotated[str | None, Field(description="Cursor for pagination")] = None,
+    page_size: Annotated[int | None, Field(description="Number of results per page")] = None,
 ) -> str:
     """List all users in the Notion workspace.