feat(mcp): generic MCP tool source with per-node function filtering (#301)

* feat(mcp): generic MCP tool source with per-node function filtering

Adds a Model Context Protocol tool category: connect a customer MCP
server and expose its tools to the agent, with optional per-node
allow-listing of individual MCP functions.

- ToolCategory.MCP enum + alembic migration
- MCP definition validator and collision-safe function-name namespacing
- McpToolSession wrapper: graceful-degrade, per-call open/close lifecycle
- CustomToolManager MCP branch (schemas + proxy handlers)
- Per-node mcp_tool_filters threaded through DTO/graph/engine
- Best-effort discovered_tools catalog cache + POST /tools/{uuid}/mcp/refresh
- UI: MCP create/edit config, tabbed ToolSelector with per-node toggles

* feat: refactor for code standardisation and documentation

---------

Co-authored-by: Abhishek Kumar <abhishek@a6k.me>

api/alembic/versions/0a1b2c3d4e5f_add_mcp_in_toolcategory.py

@@ -0,0 +1,64 @@
+"""add mcp in ToolCategory
+
+Revision ID: 0a1b2c3d4e5f
+Revises: 4c1f1e3e8ef2
+Create Date: 2026-05-16 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+from alembic_postgresql_enum import TableReference
+
+# revision identifiers, used by Alembic.
+revision: str = "0a1b2c3d4e5f"
+down_revision: Union[str, None] = "4c1f1e3e8ef2"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.sync_enum_values(
+        enum_schema="public",
+        enum_name="tool_category",
+        new_values=[
+            "http_api",
+            "end_call",
+            "transfer_call",
+            "calculator",
+            "native",
+            "integration",
+            "mcp",
+        ],
+        affected_columns=[
+            TableReference(
+                table_schema="public", table_name="tools", column_name="category"
+            )
+        ],
+        enum_values_to_rename=[],
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.sync_enum_values(
+        enum_schema="public",
+        enum_name="tool_category",
+        new_values=[
+            "http_api",
+            "end_call",
+            "transfer_call",
+            "calculator",
+            "native",
+            "integration",
+        ],
+        affected_columns=[
+            TableReference(
+                table_schema="public", table_name="tools", column_name="category"
+            )
+        ],
+        enum_values_to_rename=[],
+    )