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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ldraney-notion-mcp
-Version: 0.1.3
+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.3 → 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.3"
+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.3 → 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.3
+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.3 → 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,7 +51,10 @@ 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.
@@ -68,8 +75,8 @@ 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.
 
@@ -91,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.3 → ldraney_notion_mcp-0.1.4}/src/notion_mcp/tools/comments.py

@@ -3,15 +3,18 @@
 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.
 
@@ -41,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.3 → 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,9 +17,9 @@ 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.
 
@@ -45,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
@@ -63,11 +67,11 @@ 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.
 
@@ -97,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:
@@ -112,11 +118,11 @@ 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.
 
@@ -151,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:
@@ -166,8 +174,8 @@ 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.
 
@@ -189,11 +197,11 @@ 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.
 
@@ -221,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.3 → ldraney_notion_mcp-0.1.4}/src/notion_mcp/tools/pages.py

@@ -3,17 +3,19 @@
 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.
 
@@ -41,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:
@@ -56,11 +60,11 @@ 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.
 
@@ -93,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:
@@ -107,7 +113,10 @@ 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.

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

@@ -3,17 +3,20 @@
 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.
 

{ldraney_notion_mcp-0.1.3 → 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.