Fix bugs and enhance vector tools

Author: chengbiao-jin

pyTigerGraph/mcp/MCP_README.md

@@ -147,11 +147,10 @@ These operations manage individual graphs within the TigerGraph database. A data
 - `tigergraph__clear_graph_data` - Clear all data from a graph (keeps schema structure)
 
 ### Schema Operations (Graph Level)
-These operations work with the schema of a specific graph. Each graph has its own independent schema.
+These operations work with the schema and objects of a specific graph.
 
-- `tigergraph__get_graph_schema` - Get the schema of a specific graph (raw JSON)
-- `tigergraph__describe_graph` - Get a human-readable description of a specific graph's schema
-- `tigergraph__get_graph_metadata` - Get metadata about a specific graph (vertex types, edge types, queries, loading jobs)
+- `tigergraph__get_graph_schema` - Get the schema of a specific graph as structured JSON (vertex/edge types and attributes only)
+- `tigergraph__show_graph_details` - Show details of a graph: schema, queries, loading jobs, data sources. Use `detail_type` to filter (`schema`, `query`, `loading_job`, `data_source`) or omit for all
 
 ### Node Operations
 - `tigergraph__add_node` - Add a single node
@@ -196,15 +195,20 @@ These operations work with the schema of a specific graph. Each graph has its ow
 - `tigergraph__get_node_degree` - Get the degree (number of edges) of a node
 
 ### GSQL Operations
-- `tigergraph__gsql` - Execute GSQL command
+- `tigergraph__gsql` - Execute raw GSQL command
+- `tigergraph__generate_gsql` - Generate a GSQL query from a natural language description (requires LLM configuration)
+- `tigergraph__generate_cypher` - Generate an openCypher query from a natural language description (requires LLM configuration)
 
 ### Vector Schema Operations
 - `tigergraph__add_vector_attribute` - Add a vector attribute to a vertex type (DIMENSION, METRIC: COSINE/L2/IP)
 - `tigergraph__drop_vector_attribute` - Drop a vector attribute from a vertex type
+- `tigergraph__list_vector_attributes` - List vector attributes (name, dimension, index type, data type, metric) by parsing `LS` output; optionally filter by vertex type
 - `tigergraph__get_vector_index_status` - Check vector index rebuild status (Ready_for_query/Rebuild_processing)
 
 ### Vector Data Operations
 - `tigergraph__upsert_vectors` - Upsert multiple vertices with vector data using REST API (batch support)
+- `tigergraph__load_vectors_from_csv` - Bulk-load vectors from a CSV/delimited file via a GSQL loading job (creates job, runs with file, drops job)
+- `tigergraph__load_vectors_from_json` - Bulk-load vectors from a JSON Lines (.jsonl) file via a GSQL loading job with `JSON_FILE="true"` (creates job, runs with file, drops job)
 - `tigergraph__search_top_k_similarity` - Perform vector similarity search using `vectorSearch()` function
 - `tigergraph__fetch_vector` - Fetch vertices with vector data using GSQL `PRINT WITH VECTOR`
 
@@ -219,6 +223,11 @@ These operations work with the schema of a specific graph. Each graph has its ow
 - `tigergraph__drop_all_data_sources` - Drop all data sources
 - `tigergraph__preview_sample_data` - Preview sample data from a file
 
+### Discovery & Navigation
+- `tigergraph__discover_tools` - Search for tools by description, use case, or keywords
+- `tigergraph__get_workflow` - Get step-by-step workflow templates for common tasks (e.g., `data_loading`, `schema_creation`, `graph_exploration`)
+- `tigergraph__get_tool_info` - Get detailed information about a specific tool (parameters, examples, related tools)
+
 ## Backward Compatibility
 
 All existing pyTigerGraph APIs continue to work as before. MCP support is completely optional and does not affect existing code. The MCP functionality is only available when:
@@ -294,12 +303,91 @@ asyncio.run(call_tool())
 
 **Note:** When using `MultiServerMCPClient` or similar MCP clients with stdio transport, the `args` parameter is required. For the `tigergraph-mcp` command (which is a standalone entry point), set `args` to an empty list `[]`. If you need to pass arguments to the command, include them in the list (e.g., `["-v"]` for verbose mode, `["-vv"]` for debug mode).
 
+## LLM-Friendly Features
+
+The MCP server is designed to help AI agents work effectively with TigerGraph.
+
+### Structured Responses
+
+Every tool response follows a consistent JSON structure:
+
+```json
+{
+  "success": true,
+  "operation": "get_node",
+  "summary": "Found vertex 'p123' of type 'Person'",
+  "data": { ... },
+  "suggestions": [
+    "View connected edges: get_node_edges(...)",
+    "Find neighbors: get_neighbors(...)"
+  ],
+  "metadata": { "graph_name": "MyGraph" }
+}
+```
+
+Error responses include actionable recovery hints:
+
+```json
+{
+  "success": false,
+  "operation": "get_node",
+  "error": "Vertex not found",
+  "suggestions": [
+    "Verify the vertex_id is correct",
+    "Check vertex type with show_graph_details()"
+  ]
+}
+```
+
+### Rich Tool Descriptions
+
+Each tool includes detailed descriptions with:
+- **Use cases** — when to call this tool
+- **Common workflows** — step-by-step patterns
+- **Tips** — best practices and gotchas
+- **Warnings** — safety notes for destructive operations
+- **Related tools** — what to call next
+
+### Token Optimization
+
+Responses are designed for efficient LLM token usage:
+- No echoing of input parameters (the LLM already knows what it sent)
+- Only returns new information (results, counts, boolean answers)
+- Clean text output with no decorative formatting
+
+## Tool Discovery Workflow
+
+The MCP server includes discovery tools to help AI agents find the right tool for a task:
+
+```python
+# 1. Discover tools for a task
+result = await session.call_tool(
+    "tigergraph__discover_tools",
+    arguments={"query": "how to add data to the graph"}
+)
+# Returns: ranked list of relevant tools with use cases
+
+# 2. Get a workflow template
+result = await session.call_tool(
+    "tigergraph__get_workflow",
+    arguments={"workflow_type": "data_loading"}
+)
+# Returns: step-by-step guide with tool calls
+
+# 3. Get detailed tool info
+result = await session.call_tool(
+    "tigergraph__get_tool_info",
+    arguments={"tool_name": "tigergraph__add_node"}
+)
+# Returns: full documentation, examples, related tools
+```
+
 ## Notes
 
 - **Async APIs**: All MCP tools use pyTigerGraph's async APIs (`AsyncTigerGraphConnection`) for optimal performance
 - **Transport**: The MCP server uses stdio transport by default
-- **Tool Responses**: All tools are async and return `TextContent` responses
-- **Error Handling**: Error handling is built into each tool
+- **Structured Responses**: All tools return structured JSON responses with `success`, `operation`, `summary`, `data`, `suggestions`, and `metadata` fields. Error responses include recovery hints and contextual suggestions
+- **Error Detection**: GSQL operations include error detection for syntax and semantic errors (since `conn.gsql()` does not raise Python exceptions for GSQL failures)
 - **Connection Management**: The connection manager automatically creates async connections from environment variables
-- **Performance**: Using async APIs ensures non-blocking I/O operations, making the MCP server more efficient for concurrent requests
+- **Performance**: Async APIs for non-blocking I/O; `v.outdegree()` for O(1) degree counting; batch operations for multiple vertices/edges
 

pyTigerGraph/mcp/response_formatter.py

@@ -171,15 +171,15 @@ def format_error(
         if any(term in error_lower for term in ["vertex type", "edge type", "type not found"]):
             suggestions.extend([
                 "The specified type may not exist in the schema",
-                "Call 'describe_graph' to see available vertex and edge types",
+                "Call 'show_graph_details' to see available vertex and edge types",
                 "Call 'list_graphs' to ensure you're using the correct graph"
             ])
 
         # Attribute errors
         elif any(term in error_lower for term in ["attribute", "column", "field"]):
             suggestions.extend([
                 "One or more attributes may not match the schema definition",
-                "Call 'describe_graph' to see required attributes and their types",
+                "Call 'show_graph_details' to see required attributes and their types",
                 "Check that attribute names are spelled correctly"
             ])
 
@@ -207,7 +207,7 @@ def format_error(
                 "Query syntax error detected",
                 "For GSQL: Use 'INTERPRET QUERY () FOR GRAPH <name> { ... }'",
                 "For Cypher: Use 'INTERPRET OPENCYPHER QUERY () FOR GRAPH <name> { ... }'",
-                "Call 'describe_graph' to understand the schema before writing queries"
+                "Call 'show_graph_details' to understand the schema before writing queries"
             ])
 
         # Vector errors
@@ -216,14 +216,14 @@ def format_error(
                 "Vector operation error",
                 "Ensure vector dimensions match the attribute definition",
                 "Call 'get_vector_index_status' to check if index is ready",
-                "Verify vector attribute exists with 'describe_graph'"
+                "Verify vector attribute exists with 'show_graph_details'"
             ])
 
         # Generic suggestions
         if len(suggestions) == 0:
             suggestions.extend([
                 "Check the error message for specific details",
-                "Call 'describe_graph' to understand the current graph structure",
+                "Call 'show_graph_details' to understand the current graph structure",
                 "Verify all required parameters are provided correctly"
             ])
 
@@ -253,6 +253,27 @@ def format_error(
     )
 
 
+def gsql_has_error(result_str: str) -> bool:
+    """Check whether a GSQL result string indicates a failure.
+
+    ``conn.gsql()`` does **not** raise an exception when a GSQL command fails;
+    instead, the error message is returned as a plain string.  This helper
+    inspects the result for well-known error patterns so callers can
+    distinguish success from failure.
+    """
+    error_patterns = [
+        "Encountered \"",
+        "SEMANTIC ERROR",
+        "Syntax Error",
+        "Failed to create",
+        "does not exist",
+        "is not a valid",
+        "already exists",
+        "Invalid syntax",
+    ]
+    return any(p in result_str for p in error_patterns)
+
+
 def format_list_response(
     operation: str,
     items: List[Any],

pyTigerGraph/mcp/server.py

@@ -26,8 +26,7 @@
     clear_graph_data,
     # Schema operations (graph level)
     get_graph_schema,
-    describe_graph,
-    get_graph_metadata,
+    show_graph_details,
     # Node tools
     add_node,
     add_nodes,
@@ -72,9 +71,12 @@
     # Vector schema tools
     add_vector_attribute,
     drop_vector_attribute,
+    list_vector_attributes,
     get_vector_index_status,
     # Vector data tools
     upsert_vectors,
+    load_vectors_from_csv,
+    load_vectors_from_json,
     search_top_k_similarity,
     fetch_vector,
     # Data Source tools
@@ -130,10 +132,8 @@ async def call_tool(name: str, arguments: Dict) -> List[TextContent]:
                     # Schema operations (graph level)
                     case TigerGraphToolName.GET_GRAPH_SCHEMA:
                         return await get_graph_schema(**arguments)
-                    case TigerGraphToolName.DESCRIBE_GRAPH:
-                        return await describe_graph(**arguments)
-                    case TigerGraphToolName.GET_GRAPH_METADATA:
-                        return await get_graph_metadata(**arguments)
+                    case TigerGraphToolName.SHOW_GRAPH_DETAILS:
+                        return await show_graph_details(**arguments)
                     # Node operations
                     case TigerGraphToolName.ADD_NODE:
                         return await add_node(**arguments)
@@ -215,11 +215,17 @@ async def call_tool(name: str, arguments: Dict) -> List[TextContent]:
                         return await add_vector_attribute(**arguments)
                     case TigerGraphToolName.DROP_VECTOR_ATTRIBUTE:
                         return await drop_vector_attribute(**arguments)
+                    case TigerGraphToolName.LIST_VECTOR_ATTRIBUTES:
+                        return await list_vector_attributes(**arguments)
                     case TigerGraphToolName.GET_VECTOR_INDEX_STATUS:
                         return await get_vector_index_status(**arguments)
                     # Vector data operations
                     case TigerGraphToolName.UPSERT_VECTORS:
                         return await upsert_vectors(**arguments)
+                    case TigerGraphToolName.LOAD_VECTORS_FROM_CSV:
+                        return await load_vectors_from_csv(**arguments)
+                    case TigerGraphToolName.LOAD_VECTORS_FROM_JSON:
+                        return await load_vectors_from_json(**arguments)
                     case TigerGraphToolName.SEARCH_TOP_K_SIMILARITY:
                         return await search_top_k_similarity(**arguments)
                     case TigerGraphToolName.FETCH_VECTOR:

pyTigerGraph/mcp/tool_metadata.py

@@ -38,26 +38,26 @@ class ToolMetadata(BaseModel):
 # Define metadata for each tool
 TOOL_METADATA: Dict[str, ToolMetadata] = {
     # Schema Operations
-    "tigergraph__describe_graph": ToolMetadata(
+    "tigergraph__show_graph_details": ToolMetadata(
         category=ToolCategory.SCHEMA,
         prerequisites=[],
-        related_tools=["tigergraph__get_graph_schema", "tigergraph__get_graph_metadata"],
+        related_tools=["tigergraph__get_graph_schema"],
         common_next_steps=["tigergraph__add_node", "tigergraph__add_edge", "tigergraph__run_query"],
         use_cases=[
+            "Getting a full listing of a graph (schema, queries, jobs)",
             "Understanding the structure of a graph before writing queries",
             "Discovering available vertex and edge types",
-            "Learning the attributes of each vertex/edge type",
             "First step in any graph interaction workflow"
         ],
         complexity="basic",
-        keywords=["schema", "structure", "describe", "understand", "explore"],
+        keywords=["schema", "structure", "show", "understand", "explore", "queries", "jobs"],
         examples=[
             {
-                "description": "Get schema for default graph",
+                "description": "Show everything under default graph",
                 "parameters": {}
             },
             {
-                "description": "Get schema for specific graph",
+                "description": "Show everything under a specific graph",
                 "parameters": {"graph_name": "SocialGraph"}
             }
         ]
@@ -66,8 +66,8 @@ class ToolMetadata(BaseModel):
     "tigergraph__list_graphs": ToolMetadata(
         category=ToolCategory.SCHEMA,
         prerequisites=[],
-        related_tools=["tigergraph__describe_graph", "tigergraph__create_graph"],
-        common_next_steps=["tigergraph__describe_graph"],
+        related_tools=["tigergraph__show_graph_details", "tigergraph__create_graph"],
+        common_next_steps=["tigergraph__show_graph_details"],
         use_cases=[
             "Discovering what graphs exist in the database",
             "First step when connecting to a new TigerGraph instance",
@@ -81,8 +81,8 @@ class ToolMetadata(BaseModel):
     "tigergraph__create_graph": ToolMetadata(
         category=ToolCategory.SCHEMA,
         prerequisites=[],
-        related_tools=["tigergraph__list_graphs", "tigergraph__describe_graph"],
-        common_next_steps=["tigergraph__describe_graph", "tigergraph__add_node"],
+        related_tools=["tigergraph__list_graphs", "tigergraph__show_graph_details"],
+        common_next_steps=["tigergraph__show_graph_details", "tigergraph__add_node"],
         use_cases=[
             "Creating a new graph from scratch",
             "Setting up a graph with specific vertex and edge types",
@@ -119,7 +119,7 @@ class ToolMetadata(BaseModel):
     "tigergraph__get_graph_schema": ToolMetadata(
         category=ToolCategory.SCHEMA,
         prerequisites=[],
-        related_tools=["tigergraph__describe_graph"],
+        related_tools=["tigergraph__show_graph_details"],
         common_next_steps=["tigergraph__add_node", "tigergraph__run_query"],
         use_cases=[
             "Getting raw JSON schema for programmatic processing",
@@ -133,7 +133,7 @@ class ToolMetadata(BaseModel):
     # Node Operations
     "tigergraph__add_node": ToolMetadata(
         category=ToolCategory.DATA,
-        prerequisites=["tigergraph__describe_graph"],
+        prerequisites=["tigergraph__show_graph_details"],
         related_tools=["tigergraph__add_nodes", "tigergraph__get_node", "tigergraph__delete_node"],
         common_next_steps=["tigergraph__get_node", "tigergraph__add_edge", "tigergraph__get_node_edges"],
         use_cases=[
@@ -165,7 +165,7 @@ class ToolMetadata(BaseModel):
 
     "tigergraph__add_nodes": ToolMetadata(
         category=ToolCategory.DATA,
-        prerequisites=["tigergraph__describe_graph"],
+        prerequisites=["tigergraph__show_graph_details"],
         related_tools=["tigergraph__add_node", "tigergraph__get_nodes"],
         common_next_steps=["tigergraph__get_vertex_count", "tigergraph__add_edges"],
         use_cases=[
@@ -239,7 +239,7 @@ class ToolMetadata(BaseModel):
     # Edge Operations
     "tigergraph__add_edge": ToolMetadata(
         category=ToolCategory.DATA,
-        prerequisites=["tigergraph__add_node", "tigergraph__describe_graph"],
+        prerequisites=["tigergraph__add_node", "tigergraph__show_graph_details"],
         related_tools=["tigergraph__add_edges", "tigergraph__get_edge"],
         common_next_steps=["tigergraph__get_node_edges", "tigergraph__get_neighbors"],
         use_cases=[
@@ -266,7 +266,7 @@ class ToolMetadata(BaseModel):
 
     "tigergraph__add_edges": ToolMetadata(
         category=ToolCategory.DATA,
-        prerequisites=["tigergraph__add_nodes", "tigergraph__describe_graph"],
+        prerequisites=["tigergraph__add_nodes", "tigergraph__show_graph_details"],
         related_tools=["tigergraph__add_edge"],
         common_next_steps=["tigergraph__get_edge_count"],
         use_cases=[
@@ -282,7 +282,7 @@ class ToolMetadata(BaseModel):
     # Query Operations
     "tigergraph__run_query": ToolMetadata(
         category=ToolCategory.QUERY,
-        prerequisites=["tigergraph__describe_graph"],
+        prerequisites=["tigergraph__show_graph_details"],
         related_tools=["tigergraph__run_installed_query", "tigergraph__get_neighbors"],
         common_next_steps=[],
         use_cases=[
@@ -336,7 +336,7 @@ class ToolMetadata(BaseModel):
     # Vector Operations
     "tigergraph__add_vector_attribute": ToolMetadata(
         category=ToolCategory.VECTOR,
-        prerequisites=["tigergraph__describe_graph"],
+        prerequisites=["tigergraph__show_graph_details"],
         related_tools=["tigergraph__drop_vector_attribute", "tigergraph__get_vector_index_status"],
         common_next_steps=["tigergraph__get_vector_index_status", "tigergraph__upsert_vectors"],
         use_cases=[
@@ -426,7 +426,7 @@ class ToolMetadata(BaseModel):
     # Loading Operations
     "tigergraph__create_loading_job": ToolMetadata(
         category=ToolCategory.LOADING,
-        prerequisites=["tigergraph__describe_graph"],
+        prerequisites=["tigergraph__show_graph_details"],
         related_tools=["tigergraph__run_loading_job_with_file", "tigergraph__run_loading_job_with_data"],
         common_next_steps=["tigergraph__run_loading_job_with_file", "tigergraph__get_loading_jobs"],
         use_cases=[