fix: classify Claude MCP tools and repair setup metadata

seedream/README.md

@@ -62,7 +62,7 @@ The hosted service advertises OAuth metadata and Dynamic Client Registration (DC
 ### Hosted OAuth examples
 
 - **Claude and Claude Desktop chat:** Add a remote custom connector in `Customize → Connectors → Add custom connector`, enter `https://seedream.mcp.acedata.cloud/mcp`, select sign-in, and choose **Register automatically** if Claude asks how to register its OAuth client. Complete consent. Claude Desktop's local `claude_desktop_config.json` is a separate setup. [Claude connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
-- **Claude Code:** `claude mcp add --transport http --scope user seedream https://seedream.mcp.acedata.cloud/mcp`, then `claude mcp login seedream`. Check `/mcp`. [Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
+- **Claude Code:** `claude mcp add --transport http --scope user seedream https://seedream.mcp.acedata.cloud/mcp`, then start `claude`, open `/mcp`, and authenticate the Seedream server. [Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
 - **Cursor:** Add a remote server with only `https://seedream.mcp.acedata.cloud/mcp`. For a project, merge the entry below into `<project>/.cursor/mcp.json`; for personal use, use `~/.cursor/mcp.json`. [Cursor MCP guide](https://cursor.com/docs/mcp).
 - **VS Code / Copilot:** Run **MCP: Add Server**, select HTTP, enter `https://seedream.mcp.acedata.cloud/mcp`, then finish the browser sign-in. New portable workspace configs use `<project>/.mcp.json`; the VS Code-specific format below uses `<project>/.vscode/mcp.json` or the user profile. Check **MCP: List Servers**. [VS Code MCP setup](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
 - **Codex:** `codex mcp add seedream --url https://seedream.mcp.acedata.cloud/mcp`, then `codex mcp login seedream`. Its user settings are in `~/.codex/config.toml`. [Official Codex MCP guide](https://developers.openai.com/codex/mcp/).
@@ -188,7 +188,7 @@ Keep this user-level file private. Self-hosted HTTP uses `mcp-seedream-pro --tra
 ### Check before using the service
 
 1. `https://seedream.mcp.acedata.cloud/health` returning `{"status":"ok"}` checks endpoint reachability only.
-2. Confirm that the MCP client loads tools. `seedream_list_models` is a reference tool; it does not verify downstream API access or balance.
+2. Confirm that the MCP client loads tools. `seedream_list_models` is a local reference tool with no generation API charge; it does not verify downstream API access or balance. Generation, editing, and decomposition create credit-consuming tasks and are marked as non-read-only operations. These annotations describe the operation; the client's version, permission settings, and organization policy determine whether it asks for approval. Review the input and current price before allowing a paid operation.
 3. If you need a full API check, call `seedream_generate_image` with your own valid input after reviewing [current service documentation](https://platform.acedata.cloud/documents/seedream-mcp?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=seedream_mcp_readme_quick_start) and displayed pricing. If the result contains a task ID, call `seedream_get_task` on that same ID until terminal success or failure. Do not resubmit the operation just to check progress.
 
 For **401**, check which auth route the client used and whether the token or OAuth session is valid. A **403** may mean an account permission or content moderation failure; read the returned error. Insufficient balance and downstream service failures need their own diagnosis. A listed tool or submitted task does not prove a successful result.

seedream/README.pypi.md

@@ -63,7 +63,7 @@ The hosted service advertises OAuth metadata and Dynamic Client Registration (DC
 ### Hosted OAuth examples
 
 - **Claude and Claude Desktop chat:** Add a remote custom connector in `Customize → Connectors → Add custom connector`, enter `https://seedream.mcp.acedata.cloud/mcp`, select sign-in, and choose **Register automatically** if Claude asks how to register its OAuth client. Complete consent. Claude Desktop's local `claude_desktop_config.json` is a separate setup. [Claude connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
-- **Claude Code:** `claude mcp add --transport http --scope user seedream https://seedream.mcp.acedata.cloud/mcp`, then `claude mcp login seedream`. Check `/mcp`. [Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
+- **Claude Code:** `claude mcp add --transport http --scope user seedream https://seedream.mcp.acedata.cloud/mcp`, then start `claude`, open `/mcp`, and authenticate the Seedream server. [Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
 - **Cursor:** Add a remote server with only `https://seedream.mcp.acedata.cloud/mcp`. For a project, merge the entry below into `<project>/.cursor/mcp.json`; for personal use, use `~/.cursor/mcp.json`. [Cursor MCP guide](https://cursor.com/docs/mcp).
 - **VS Code / Copilot:** Run **MCP: Add Server**, select HTTP, enter `https://seedream.mcp.acedata.cloud/mcp`, then finish the browser sign-in. New portable workspace configs use `<project>/.mcp.json`; the VS Code-specific format below uses `<project>/.vscode/mcp.json` or the user profile. Check **MCP: List Servers**. [VS Code MCP setup](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
 - **Codex:** `codex mcp add seedream --url https://seedream.mcp.acedata.cloud/mcp`, then `codex mcp login seedream`. Its user settings are in `~/.codex/config.toml`. [Official Codex MCP guide](https://developers.openai.com/codex/mcp/).
@@ -189,7 +189,7 @@ Keep this user-level file private. Self-hosted HTTP uses `mcp-seedream-pro --tra
 ### Check before using the service
 
 1. `https://seedream.mcp.acedata.cloud/health` returning `{"status":"ok"}` checks endpoint reachability only.
-2. Confirm that the MCP client loads tools. `seedream_list_models` is a reference tool; it does not verify downstream API access or balance.
+2. Confirm that the MCP client loads tools. `seedream_list_models` is a local reference tool with no generation API charge; it does not verify downstream API access or balance. Generation, editing, and decomposition create credit-consuming tasks and are marked as non-read-only operations. These annotations describe the operation; the client's version, permission settings, and organization policy determine whether it asks for approval. Review the input and current price before allowing a paid operation.
 3. If you need a full API check, call `seedream_generate_image` with your own valid input after reviewing [current service documentation](https://platform.acedata.cloud/documents/seedream-mcp?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=seedream_mcp_package_quick_start) and displayed pricing. If the result contains a task ID, call `seedream_get_task` on that same ID until terminal success or failure. Do not resubmit the operation just to check progress.
 
 For **401**, check which auth route the client used and whether the token or OAuth session is valid. A **403** may mean an account permission or content moderation failure; read the returned error. Insufficient balance and downstream service failures need their own diagnosis. A listed tool or submitted task does not prove a successful result.

seedream/core/server.py

@@ -47,7 +47,7 @@
 # Initialize FastMCP server
 mcp = FastMCP(
     settings.server_name,
-    icons=[Icon(src="
", mimeType="image/png")],
+    icons=[Icon(src="https://cdn.acedata.cloud/9egrbn.png", mimeType="image/png")],
     **mcp_kwargs,
 )
 

seedream/tests/test_tool_annotations.py

@@ -0,0 +1,38 @@
+"""Verify read/write permissions in the public MCP catalog."""
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from core.client import client
+from core.server import mcp
+from tools import image_tools, info_tools, task_tools  # noqa: F401
+
+
+@pytest.mark.asyncio
+async def test_catalog_marks_credit_consuming_image_operations_as_writes():
+    tools = await mcp.list_tools()
+    assert len(tools) == 7
+    writes = {"seedream_generate_image", "seedream_edit_image", "seedream_decompose_image"}
+    for tool in tools:
+        public = tool.model_dump(by_alias=True, exclude_none=True)
+        assert public["title"]
+        hints = public["annotations"]
+        is_write = tool.name in writes
+        assert hints["readOnlyHint"] is (not is_write)
+        # Writes create paid tasks; conservative consent protects account Credits.
+        assert hints["destructiveHint"] is is_write
+        assert hints["idempotentHint"] is (not is_write)
+        assert hints["openWorldHint"] is (not tool.name.startswith("seedream_list_"))
+
+
+@pytest.mark.asyncio
+async def test_reference_first_call_does_not_generate_or_query(monkeypatch):
+    generate = AsyncMock(side_effect=AssertionError("Reference calls must stay local"))
+    query = AsyncMock(side_effect=AssertionError("Reference calls must stay local"))
+    monkeypatch.setattr(client, "generate_image", generate)
+    monkeypatch.setattr(client, "query_task", query)
+    result = await mcp.call_tool("seedream_list_models", {})
+    assert result
+    generate.assert_not_awaited()
+    query.assert_not_awaited()

seedream/tools/image_tools.py

@@ -2,6 +2,7 @@
 
 from typing import Annotated
 
+from mcp.types import ToolAnnotations
 from pydantic import Field
 
 from core.client import client
@@ -18,7 +19,15 @@
 from core.utils import format_image_result
 
 
-@mcp.tool()
+@mcp.tool(
+    title="Generate a Seedream image",
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
 async def seedream_generate_image(
     prompt: Annotated[
         str,
@@ -152,7 +161,15 @@ async def seedream_generate_image(
     return format_image_result(result)
 
 
-@mcp.tool()
+@mcp.tool(
+    title="Edit an image with Seedream",
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
 async def seedream_edit_image(
     prompt: Annotated[
         str,
@@ -279,7 +296,15 @@ async def seedream_edit_image(
     return format_image_result(result)
 
 
-@mcp.tool()
+@mcp.tool(
+    title="Decompose an image with Seedream",
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
 async def seedream_decompose_image(
     image: Annotated[str, Field(description="One PNG or JPEG URL/base64 image to decompose.")],
     prompt: Annotated[

seedream/tools/info_tools.py

@@ -1,9 +1,19 @@
 """Information and reference tools for Seedream API."""
 
+from mcp.types import ToolAnnotations
+
 from core.server import mcp
 
 
-@mcp.tool()
+@mcp.tool(
+    title="List Seedream models",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    ),
+)
 async def seedream_list_models() -> str:
     """List all available Seedream models with their capabilities and pricing.
 
@@ -72,7 +82,15 @@ async def seedream_list_models() -> str:
 """
 
 
-@mcp.tool()
+@mcp.tool(
+    title="List Seedream image sizes",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    ),
+)
 async def seedream_list_sizes() -> str:
     """List all available image sizes and resolution options for Seedream.
 

seedream/tools/task_tools.py

@@ -3,14 +3,23 @@
 import asyncio
 from typing import Annotated
 
+from mcp.types import ToolAnnotations
 from pydantic import Field
 
 from core.client import client
 from core.server import mcp
 from core.utils import format_task_result
 
 
-@mcp.tool()
+@mcp.tool(
+    title="Get Seedream task result",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
 async def seedream_get_task(
     task_id: Annotated[
         str,
@@ -53,7 +62,15 @@ async def seedream_get_task(
     return format_task_result(result)
 
 
-@mcp.tool()
+@mcp.tool(
+    title="Get Seedream task results in batch",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
 async def seedream_get_tasks_batch(
     task_ids: Annotated[
         list[str],

serp/README.md

@@ -55,7 +55,7 @@ The hosted service advertises OAuth metadata and Dynamic Client Registration (DC
 ### Hosted OAuth examples
 
 - **Claude and Claude Desktop chat:** Add a remote custom connector in `Customize → Connectors → Add custom connector`, enter `https://serp.mcp.acedata.cloud/mcp`, select sign-in, and choose **Register automatically** if Claude asks how to register its OAuth client. Complete consent. Claude Desktop's local `claude_desktop_config.json` is a separate setup. [Claude connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
-- **Claude Code:** `claude mcp add --transport http --scope user serp https://serp.mcp.acedata.cloud/mcp`, then `claude mcp login serp`. Check `/mcp`. [Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
+- **Claude Code:** `claude mcp add --transport http --scope user serp https://serp.mcp.acedata.cloud/mcp`, then start `claude`, open `/mcp`, and authenticate the Serp server. [Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
 - **Cursor:** Add a remote server with only `https://serp.mcp.acedata.cloud/mcp`. For a project, merge the entry below into `<project>/.cursor/mcp.json`; for personal use, use `~/.cursor/mcp.json`. [Cursor MCP guide](https://cursor.com/docs/mcp).
 - **VS Code / Copilot:** Run **MCP: Add Server**, select HTTP, enter `https://serp.mcp.acedata.cloud/mcp`, then finish the browser sign-in. New portable workspace configs use `<project>/.mcp.json`; the VS Code-specific format below uses `<project>/.vscode/mcp.json` or the user profile. Check **MCP: List Servers**. [VS Code MCP setup](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
 - **Codex:** `codex mcp add serp --url https://serp.mcp.acedata.cloud/mcp`, then `codex mcp login serp`. Its user settings are in `~/.codex/config.toml`. [Official Codex MCP guide](https://developers.openai.com/codex/mcp/).
@@ -181,7 +181,7 @@ Keep this user-level file private. Self-hosted HTTP uses `mcp-serp --transport h
 ### Check before using the service
 
 1. `https://serp.mcp.acedata.cloud/health` returning `{"status":"ok"}` checks endpoint reachability only.
-2. Confirm that the MCP client loads tools. `serp_get_usage_guide` is a reference tool; it does not verify downstream API access or balance.
+2. Confirm that the MCP client loads tools. `serp_list_search_types` and `serp_get_usage_guide` are local reference tools with no search API charge; they do not verify downstream API access or balance. Search tools are read-only but consume Credits, and repeating a search can incur another charge.
 3. If you need a full API check, call `serp_google_search` with your own valid input after reviewing [current service documentation](https://platform.acedata.cloud/documents/serp-mcp?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=serp_mcp_readme_quick_start) and displayed pricing.
 
 For **401**, check which auth route the client used and whether the token or OAuth session is valid. A **403** may mean an account permission or content moderation failure; read the returned error. Insufficient balance and downstream service failures need their own diagnosis. A listed tool or submitted task does not prove a successful result.

serp/README.pypi.md

@@ -56,7 +56,7 @@ The hosted service advertises OAuth metadata and Dynamic Client Registration (DC
 ### Hosted OAuth examples
 
 - **Claude and Claude Desktop chat:** Add a remote custom connector in `Customize → Connectors → Add custom connector`, enter `https://serp.mcp.acedata.cloud/mcp`, select sign-in, and choose **Register automatically** if Claude asks how to register its OAuth client. Complete consent. Claude Desktop's local `claude_desktop_config.json` is a separate setup. [Claude connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
-- **Claude Code:** `claude mcp add --transport http --scope user serp https://serp.mcp.acedata.cloud/mcp`, then `claude mcp login serp`. Check `/mcp`. [Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
+- **Claude Code:** `claude mcp add --transport http --scope user serp https://serp.mcp.acedata.cloud/mcp`, then start `claude`, open `/mcp`, and authenticate the Serp server. [Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
 - **Cursor:** Add a remote server with only `https://serp.mcp.acedata.cloud/mcp`. For a project, merge the entry below into `<project>/.cursor/mcp.json`; for personal use, use `~/.cursor/mcp.json`. [Cursor MCP guide](https://cursor.com/docs/mcp).
 - **VS Code / Copilot:** Run **MCP: Add Server**, select HTTP, enter `https://serp.mcp.acedata.cloud/mcp`, then finish the browser sign-in. New portable workspace configs use `<project>/.mcp.json`; the VS Code-specific format below uses `<project>/.vscode/mcp.json` or the user profile. Check **MCP: List Servers**. [VS Code MCP setup](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
 - **Codex:** `codex mcp add serp --url https://serp.mcp.acedata.cloud/mcp`, then `codex mcp login serp`. Its user settings are in `~/.codex/config.toml`. [Official Codex MCP guide](https://developers.openai.com/codex/mcp/).
@@ -182,7 +182,7 @@ Keep this user-level file private. Self-hosted HTTP uses `mcp-serp --transport h
 ### Check before using the service
 
 1. `https://serp.mcp.acedata.cloud/health` returning `{"status":"ok"}` checks endpoint reachability only.
-2. Confirm that the MCP client loads tools. `serp_get_usage_guide` is a reference tool; it does not verify downstream API access or balance.
+2. Confirm that the MCP client loads tools. `serp_list_search_types` and `serp_get_usage_guide` are local reference tools with no search API charge; they do not verify downstream API access or balance. Search tools are read-only but consume Credits, and repeating a search can incur another charge.
 3. If you need a full API check, call `serp_google_search` with your own valid input after reviewing [current service documentation](https://platform.acedata.cloud/documents/serp-mcp?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=serp_mcp_package_quick_start) and displayed pricing.
 
 For **401**, check which auth route the client used and whether the token or OAuth session is valid. A **403** may mean an account permission or content moderation failure; read the returned error. Insufficient balance and downstream service failures need their own diagnosis. A listed tool or submitted task does not prove a successful result.

serp/core/server.py

@@ -47,7 +47,7 @@
 # Initialize FastMCP server
 mcp = FastMCP(
     settings.server_name,
-    icons=[Icon(src="
", mimeType="image/png")],
+    icons=[Icon(src="https://cdn.acedata.cloud/2870040497.png", mimeType="image/png")],
     **mcp_kwargs,
 )