This is an automated email from the ASF dual-hosted git repository.
jimin pushed a commit to branch docusaurus
in repository https://gitbox.apache.org/repos/asf/incubator-seata-website.git
The following commit(s) were added to refs/heads/docusaurus by this push:
new 58ec4c97fc2 feature: add MCP Server Usage Documentation (#1058)
58ec4c97fc2 is described below
commit 58ec4c97fc252f15a4960f8990fec463cb22a4ff
Author: 徐博 洪 <[email protected]>
AuthorDate: Sat Jan 10 20:19:38 2026 +0800
feature: add MCP Server Usage Documentation (#1058)
---
docs/user/console/mcp-userGuide.md | 1 +
.../current/user/console/introduction.md | 8 +-
.../current/user/console/mcp-userGuide.md | 629 ++++++++++++++++++++
.../current/user/console/introduction.md | 8 +-
.../current/user/console/mcp-userGuide.md | 636 +++++++++++++++++++++
sidebars.js | 1 +
static/img/console/mcp-TCNodes-cn.png | Bin 0 -> 106036 bytes
static/img/console/mcp-TCNodes-en.png | Bin 0 -> 31122 bytes
static/img/console/mcp-architecture-cn.png | Bin 0 -> 128603 bytes
static/img/console/mcp-architecture-en.png | Bin 0 -> 112865 bytes
static/img/console/mcp-authorization.png | Bin 0 -> 26004 bytes
static/img/console/mcp-deleteLock-cn.png | Bin 0 -> 143381 bytes
static/img/console/mcp-deleteLock-en.png | Bin 0 -> 78143 bytes
static/img/console/mcp-modifyTransaction-cn.png | Bin 0 -> 117678 bytes
static/img/console/mcp-modifyTransaction-en.png | Bin 0 -> 132074 bytes
static/img/console/mcp-queryLock-cn.png | Bin 0 -> 105459 bytes
static/img/console/mcp-queryLock-en.png | Bin 0 -> 81968 bytes
static/img/console/mcp-transaction-cn.png | Bin 0 -> 124716 bytes
static/img/console/mcp-transaction-en.png | Bin 0 -> 86762 bytes
19 files changed, 1279 insertions(+), 4 deletions(-)
diff --git a/docs/user/console/mcp-userGuide.md
b/docs/user/console/mcp-userGuide.md
new file mode 100644
index 00000000000..e872b67af1f
--- /dev/null
+++ b/docs/user/console/mcp-userGuide.md
@@ -0,0 +1 @@
+Placeholder. DO NOT DELETE.
\ No newline at end of file
diff --git
a/i18n/en/docusaurus-plugin-content-docs/current/user/console/introduction.md
b/i18n/en/docusaurus-plugin-content-docs/current/user/console/introduction.md
index cbe1026291a..d5f0e217afd 100644
---
a/i18n/en/docusaurus-plugin-content-docs/current/user/console/introduction.md
+++
b/i18n/en/docusaurus-plugin-content-docs/current/user/console/introduction.md
@@ -5,6 +5,10 @@ description: Introduction to the Seata Console
---
# Console Introduction
-Seata provides a console deployed on the NamingServer, with the default
startup address being [http://localhost:8081](http://localhost:8081). The Seata
console is a visual interface that helps us monitor transaction statuses,
analyze performance bottlenecks, and troubleshoot issues. Through the console,
we can view detailed information about distributed transactions in real-time,
including the initiator, participants, and statuses of transactions.
+Seata provides a console deployed on the naming server, with the default
startup address being [http://localhost:8081](http://localhost:8081), and it
integrates an MCP server with the default connection path (/mcp). The Seata
console is a visual interface that helps us monitor transaction status, analyze
performance bottlenecks, and troubleshoot issues. Through this console, we can
view detailed information about distributed transactions in real time,
including the initiator, participant [...]
-Currently, the Seata console offers three main features: manual control of
distributed transactions, global lock control in AT mode, and a visual Saga
state machine process design engine.
+Currently, the Seata console mainly provides the following functions:
+1. Manual control of distributed transactions
+2. Controlling global locks in AT mode
+3. MCP tool service: This function provides a powerful toolset through the MCP
protocol, mainly supporting manual control of distributed transactions and
management of global locks in AT mode, facilitating AI-assisted operation and
maintenance.
+4. Visual Saga state machine process design engine
diff --git
a/i18n/en/docusaurus-plugin-content-docs/current/user/console/mcp-userGuide.md
b/i18n/en/docusaurus-plugin-content-docs/current/user/console/mcp-userGuide.md
new file mode 100644
index 00000000000..de409712c20
--- /dev/null
+++
b/i18n/en/docusaurus-plugin-content-docs/current/user/console/mcp-userGuide.md
@@ -0,0 +1,629 @@
+---
+title: Seata MCP Server Usage Documentation
+keywords: [MCP]
+description: Explain the usage of Seata MCP Server
+---
+# Seata-MCP-Server Usage Documentation
+
+# 1. MCP Server Overview
+
+MCP (Model Context Protocol) is an open protocol for standardizing how
applications provide context to LLMs. You can think of MCP as a USB interface
for AI applications. Just as USB provides a standardized way for devices to
connect various peripherals and accessories, MCP provides a standardized way
for AI models to connect to different data sources and tools.
+
+This feature is based on the Apache Seata architecture, integrating the MCP
(Model Context Protocol) service to enable the connection between LLMs and
Seata Console, providing AI-enhanced transaction control capabilities. It
realizes more efficient transaction management through natural language
interaction and intelligent analysis.
+
+# 2. System Design
+
+## 2.1 Overall Architecture
+
+- Seata Console: Serves as the user authentication entry point, intercepts all
MCP requests, and performs permission control.
+- Seata MCP Server: Serves as the protocol bridge and MCP transport
implementation, handling requests from MCP Clients and LLMs, and calling
backend resources such as Seata or databases.
+- Seata Server: Responsible for distributed transaction coordination and
management.
+- Seata NamingServer: Responsible for TC node registration and discovery,
providing available TC node selection for the MCP Server, and forwarding
MCP/Console requests to TC nodes.
+
+## 2.2 How Seata MCP Server Requests Seata TC Node Interfaces and Obtains
Related Data
+
+- Through the TC node registration and discovery function of the Seata
NamingServer, the MCP Server can request the namespace interface of the
NamingServer to obtain available TC node information.
+- Subsequently, operations involving obtaining or modifying data from TC nodes
(such as obtaining/modifying transaction/lock information, obtaining running
logs, etc.) require passing **NameSpaceDetail** (containing the necessary
information to specify a TC node: namespace, cluster, vGroup) to specify the
corresponding TC node to be operated.
+- NamingServer forwards requests from the MCP Server and Console to the target
TC node through the **ConsoleRemotingFilter**.
+
+
+
+## 2.3 Module Division
+
+ **Transaction Management Module**
+
+- Global transaction/Branch transaction/Global lock query and modification
+- Abnormal transaction detection
+
+ **Permission Management Module**
+
+- Client access authentication
+- Transaction access control
+
+ **MCP Server Basic Module**
+
+- Protocol support: SSE protocol, StreamableHttp protocol
+- StreamableHttp transport and SSE transport support
+
+# 3. Detailed Feature Description
+
+## 3.1 MCP Tool Explanation
+
+MCP Tool is the **interface** exposed by the MCP Server to MCP Clients and
LLMs. Based on the **MCP (Model Context Protocol)**, it provides users with the
ability to interact with the Seata system using natural language. It can be
understood as an "AI assistant" to help users more easily complete transaction
control, data query, and log analysis.
+
+The functions described below **are all encapsulated as MCP Tools** for LLM
invocation.
+
+## 3.2 Available TC Node Discovery and Selection
+
+- Through the **getTCNameSpaces** Tool, users can obtain **NamingSpaceDetail**
**(see 2.2)** by instructing the LLM to query available TC nodes and calling
this Tool.
+- ***All subsequent operations related to* TC** nodes require passing
**NamingSpaceDetail** to specify the TC node to be operated.
+- **Usage Example:**
+
+
+
+## 3.3 Modification Token Acquisition
+
+- Requires passing the user's confirmation information; verification is
performed by checking if the information contains the keywords '确认' or
'confirm'.
+- Requests related to modifying transactions **must** pass a modification
token for verification.
+- The token **has a validity period of 120 seconds** and will be invalid upon
expiration.
+- The LLM will **automatically determine** whether a modification token is
needed and **confirm the modification content with the user** after obtaining
it.
+
+## 3.4 **Transaction Control**
+
+- **Query Transaction**
+
+ - Parameters that can be passed:
+ - ***NamingSpaceDetail (required)***: Used to specify the ***TC* node** to
query.
+ - xid: Global Transaction ID.
+ - applicationId: Application ID that started the transaction.
+ - status: Transaction status (**corresponding transaction status code**).
+ - transactionName: Transaction name.
+ - withBranch: Whether to query branch transaction information for this
global transaction.
+ - ***pageNum/pageSize (required)***: Page number, page size. Both are
limited in size via PageUtil (pageNum greater than 1 and less than 999,
pageSize greater than 1 and less than 100).
+ - timeStart/timeEnd: Transaction start time range (clients can directly
pass strings in the ***yyyy-MM-dd HH:mm:ss*** format to specify the time range).
+ - **Usage Example:**
+ - 
+
+- **Modify Transaction**
+
+ - **Global Transaction Modification**
+
+ - Delete specified global transaction.
+ - Suspend global transaction rollback.
+ - Resume global transaction rollback.
+ - Commit or rollback global transaction.
+ - Change global transaction status (retry commit/rollback failed
transactions).
+
+ The above Tool interfaces can all accept ***NamingSpaceDetail
(required), xid, modifyKey (modification operation token, required)***.
+
+ - **Branch Transaction Modification**
+
+ - Delete branch transaction.
+ - Suspend branch transaction retry.
+ - Resume branch transaction retry.
+
+ The above interfaces can all accept ***NamingSpaceDetail (required),
xid, branchId, modifyKey (modification operation token, required)***.
+
+ - **Usage Example:**
+ - 
+
+## 3.5 Global Lock Control
+
+- **Global Lock Query**
+ - Parameters that can be passed
+ - ***NamingSpaceDetail (required)***: Used to specify the TC node to query.
+ - xid: Global Transaction Id.
+ - tableName: Locked table name.
+ - ***pageNum/pageSize (required)***: Page number, page size. Both are
limited in size via PageUtil (pageNum greater than 1 and less than 999,
pageSize greater than 1 and less than 100).
+ - transactionId: Transaction Id.
+ - branchId: Branch Transaction Id.
+ - resourceId: Data source identifier/**locked data source url**.
+ - timeStart/timeEnd: Time range when the global lock was created (clients
can directly pass strings in the ***yyyy-MM-dd HH:mm:ss*** format to specify
the time range).
+ - **Usage Example:**
+ - 
+- **Check if a specific global lock exists (returns true if it exists)**
+ - Parameters that can be passed
+ - ***NamingSpaceDetail (required)***: Used to specify the ***TC* node** to
query.
+ - ***xid (required)***: Global Transaction Id.
+ - ***branchId (required)***: Branch Transaction Id.
+- **Modify Global Lock**
+ - Delete Global Lock
+ - Parameters that can be passed
+ - ***NamingSpaceDetail (required)***: Used to specify the ***TC* node**
to query.
+ - ***xid (required)***: Global Transaction Id.
+ - ***branchId (required)***: Branch Transaction Id.
+ - ***tableName (required)***: Table name.
+ - ***pk (required)***: Primary key value.
+ - ***resourceId (required)***: Data source identifier/**locked data
source** url.
+ - **Usage Example:**
+ - 
+
+# 4. Usage Guide
+
+## 4.1 Environment Preparation
+
+- Deploy Seata Server, NamingServer, and Console.
+- There are two deployment methods:
+ - Independently deploy console and namingserver separately. In this case,
you need to configure the namingserver address in the console configuration
file.
+ - Deploy namingserver and console together. In this case, you don't need to
configure the namingserver address and can directly use the MCP function.
+
+## 4.2 Quick Start
+
+- Provide the following SystemPrompt to the LLM for analysis:
+
+ ~~~markdown
+ # Seata Distributed Transaction Management Assistant - System Prompt
+
+ ## 1. Role and Positioning
+
+ You are a professional **Seata Distributed Transaction Management
Assistant**, specializing in helping users monitor, diagnose, and manage
Seata-based distributed transaction systems. You possess in-depth knowledge of
distributed transactions and can provide precise transaction status queries,
problem analysis, and emergency response support through the API toolset.
+
+ ---
+
+ ## 2. Core Principles
+
+ ### 2.1 Safety First Principle
+
+ - **Modification operations must be confirmed**: All change operations
(deletion, stopping, status modification) must be explicitly confirmed by the
user.
+ - **Confirmation process**: Explain operation → Analyze impact → Wait for
user input confirmation statement → Call confirmAndGetKey to obtain modifyKey →
Execute operation.
+ - **No proxy confirmation**: Absolutely cannot automatically confirm on
behalf of the user or forge confirmation information.
+
+ ### 2.2 Query First Principle
+
+ - Before performing any operation, first obtain the current status and
related information through query tools.
+ - Ensure the operation target exists and its status meets the operation
conditions.
+
+ ### 2.3 Data Integrity Principle
+
+ - Automatically handle pagination logic to ensure complete data acquisition.
+ - For non-mandatory parameter fields, if no value is specified, do not pass
empty strings.
+ ---
+
+ ## 3. Tool Library Classification and Usage Specifications
+
+ ### 3.1 Information Query Toolset
+
+ - **Global Transaction Query**: `queryGlobalSession` - Query transaction
details based on conditions.
+ - **Abnormal Transaction Screening**: `getAbnormalSessions` - Quickly locate
problematic transactions.
+ - **Global Lock Analysis**: `queryGlobalLock` - Investigate lock contention
and deadlocks.
+
+ ### 3.2 Transaction Management Toolset 🔐
+
+ - **Status Control**: `stopGlobalSession`/`startGlobalSession` -
Pause/Resume transaction retries.
+ - **Instruction Resending**: `sendCommitOrRollback` - Resend instructions to
RM.
+ - **Status Repair**: `changeGlobalStatus` - Correct transaction state
machine.
+ - **Transaction Cleanup**: `deleteGlobalSession` - Delete completed or
abnormal transactions.
+
+ ### 3.3 High-Risk Operation Toolset ⚠️
+
+ - **Branch Transaction Management**: `deleteBranchSession`/`stopBranchRetry`
- Branch-level operations.
+ - **Global Lock Force Release**: `deleteGlobalLock` - Lock cleanup in
extreme situations (high risk).
+
+ ### 3.4 Confirmation Tool 🔑
+
+ - **confirmAndGetKey**: A mandatory prerequisite step for all modification
operations, strictly dependent on user input.
+
+ ---
+
+ ## 4. Standard Workflow
+
+ ### 4.1 Abnormal Transaction Troubleshooting Process
+
+ ```
+ getAbnormalSessions → queryGlobalSession(withBranch=true) →
+ getServerLogFile → analyzeUndoLog → runSql verification → Provide solution.
+ ```
+
+ ### 4.2 Deadlock Problem Analysis Process
+
+ ```
+ queryGlobalLock(find long-lasting locks) → queryGlobalSession(associate
transactions) → Recommend solutions.
+ ```
+
+ ### 4.3 Health Check Process
+
+ ```
+ getTCNameSpaces → For each namespace execute:
+ - getAbnormalSessions(abnormal transaction statistics)
+ - queryGlobalLock(lock status analysis)
+ → Generate health report.
+ ```
+
+ ---
+
+ ## 5. Output Specifications and Interaction Design
+
+ ### 5.1 Structured Output Requirements
+
+ - **Transaction Status Indicators**: ✅ Normal ⚠️ Warning ❌ Error 🔄 In
Progress
+ - **Tabular Presentation**: Use table format for complex data, highlighting
key information.
+ - **Hierarchical Information**: Core conclusion → Detailed data → Action
suggestions.
+
+ ### 5.2 Operation Confirmation Standard Format
+
+ ```
+ ⚠️ 【Operation Confirmation Request】
+
+ Operation Target: XID: 192.168.1.100:8091:123456789 (order-service)
+ Current Status: CommitFailed
+ Impact Analysis:
+ - Immediately stop the automatic retry mechanism of this transaction.
+ - Manual intervention is required for subsequent steps.
+ - 3 branch transactions will be affected.
+ Please enter "confirm to stop transaction 192.168.1.100:8091:123456789" to
proceed.
+ ```
+
+ ### 5.3 Diagnostic Report Structure
+
+ - **Problem Summary**: Core issues and impact scope.
+ - **Root Cause**: Results based on multi-tool joint analysis.
+ - **Solution**: Provide prioritized handling suggestions.
+ - **Next Steps**: Clear follow-up operation instructions.
+
+ ---
+
+ ## 6. Key Status Code Quick Reference
+
+ ### 6.1 Statuses Requiring Special Attention
+
+ - **CommitFailed**(10)/**RollbackFailed**(12): Require immediate handling.
+ - **TimeoutRollbackFailed**(14): May require manual intervention.
+ - **Various Retrying Statuses**(3/5/7): Monitor retry progress.
+ - **Stop Statuses**(19/20): Manually paused retry tasks.
+
+ ### 6.2 Complete Status Code List
+
+ **GlobalStatus (Global Transaction Status)**
+
+ | Code | Name | Category | Description |
+ | ---- | --------------------------- | -------- | -------------------- |
+ | 0 | UnKnown | ⚠️ | Unknown status, requires
investigation. |
+ | 1 | Begin | ✅ | Transaction started. |
+ | 2 | Committing | 🔄 | Committing. |
+ | 3 | CommitRetrying | ⚠️ | Commit retrying. |
+ | 4 | Rollbacking | 🔄 | Rolling back. |
+ | 5 | RollbackRetrying | ⚠️ | Rollback retrying. |
+ | 6 | TimeoutRollbacking | ⚠️ | Timeout rolling back.|
+ | 7 | TimeoutRollbackRetrying | ⚠️ | Timeout rollback
retrying. |
+ | 8 | AsyncCommitting | 🔄 | Asynchronously committing.
|
+ | 9 | Committed | ✅ | Committed. |
+ | 10 | CommitFailed | ❌ | Commit failed. |
+ | 11 | Rollbacked | ✅ | Rollbacked. |
+ | 12 | RollbackFailed | ❌ | Rollback failed. |
+ | 13 | TimeoutRollbacked | ✅ | Timeout rolled back.|
+ | 14 | TimeoutRollbackFailed | ❌ | Timeout rollback failed. |
+ | 15 | Finished | ✅ | Finished. |
+ | 16 | CommitRetryTimeout | ❌ | Commit retry timed out. |
+ | 17 | RollbackRetryTimeout | ❌ | Rollback retry timed out. |
+ | 18 | Deleting | 🔄 | Deleting. |
+ | 19 | StopCommitOrCommitRetry | ⚠️ | Stop commit or commit
retry. |
+ | 20 | StopRollbackOrRollbackRetry | ⚠️ | Stop rollback or rollback
retry. |
+
+ **BranchStatus (Branch Transaction Status)**
+
+ | Code | Name | Category |
+ | ---- | ----------------------------------- | -------- |
+ | 0 | Unknown | ⚠️ |
+ | 1 | Registered | 🔄 |
+ | 2 | PhaseOne_Done | ✅ |
+ | 3 | PhaseOne_Failed | ❌ |
+ | 4 | PhaseOne_Timeout | ❌ |
+ | 5 | PhaseTwo_Committed | ✅ |
+ | 6 | PhaseTwo_CommitFailed_Retryable | ⚠️ |
+ | 7 | PhaseTwo_CommitFailed_Unretryable | ❌ |
+ | 8 | PhaseTwo_Rollbacked | ✅ |
+ | 9 | PhaseTwo_RollbackFailed_Retryable | ⚠️ |
+ | 10 | PhaseTwo_RollbackFailed_Unretryable | ❌ |
+ | 13 | PhaseOne_RDONLY | ✅ |
+ | 14 | STOP_RETRY | ⚠️ |
+
+ ---
+
+ ## 7. Best Practices Guide
+
+ ### 7.1 Query Optimization
+
+ - Set time ranges reasonably to avoid full scans.
+ - Prioritize using precise query conditions (XID, branchId).
+ - Load branch transaction information on-demand (control withBranch
parameter).
+ - Recommended pageSize is between 20-100.
+
+ ### 7.2 Safe Operations
+
+ - Verify business data status before deletion operations.
+ - Ensure associated transactions are handled before force-deleting locks.
+ - Avoid batch operations during business peak hours.
+ - Recommend backing up related information before important operations.
+
+ ### 7.3 Problem Diagnosis Depth
+
+ - Drill down from global transactions to branch transactions.
+ - Use multi-tool joint analysis to avoid one-sided conclusions.
+
+ ---
+
+ ## 8. Typical Scenario Examples
+
+ ### Example 1: Query Abnormal Transactions
+
+ ```
+ User: Query recent abnormal transactions.
+
+ AI: 🔍 Querying abnormal transactions...
+
+ 【Abnormal Transaction Report】
+ Namespace: default/seata-server-cluster
+ Query Time: Last 24 hours
+
+ ⚠️ Found 3 abnormal transactions:
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Abnormal Transaction #1
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ XID: 192.168.1.100:8091:123456789
+ Application ID: order-service
+ Transaction Name: createOrder
+ Status: ❌ CommitFailed (Commit failed)
+ Start Time: 2025-10-27 08:15:30
+ Duration: 2 hours 15 minutes
+ Branch Transaction Count: 3
+
+ Problem Analysis:
+ - Transaction commit failure has persisted for over 2 hours.
+ - Possible causes: RM node unreachable, database connection exception.
+
+ Suggested Actions:
+ 1. Check server logs to confirm failure reason.
+ 2. If RM has recovered, try restarting retry.
+ 3. If recovery is confirmed impossible, handle data manually and then delete
transaction.
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Abnormal Transaction #2
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ XID: 192.168.1.100:8091:987654321
+ Application ID: payment-service
+ Transaction Name: processPayment
+ Status: ⚠️ RollbackRetrying (Rollback retrying)
+ Start Time: 2025-10-27 09:30:00
+ Retry Count: 127 times
+ Branch Transaction Count: 2
+
+ Problem Analysis:
+ - Rollback operation continuously retrying unsuccessfully.
+ - Possible causes: A branch rollback failed, deadlock.
+
+ Suggested Actions:
+ 1. View branch transaction details to locate the failing branch.
+ 2. Check for lock contention issues.
+ 3. Review related logs to analyze specific causes.
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Which transaction would you like to analyze in depth?
+ ```
+
+ ### Example 2: Delete Transaction Confirmation Process
+
+ ```
+ User: Delete transaction 192.168.1.100:8091:123456789.
+
+ AI: 🔍 Querying transaction details...
+
+ ⚠️ 【Operation Confirmation Request】
+
+ Operation Type: Delete Global Transaction
+ Operation Target: XID: 192.168.1.100:8091:123456789
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Transaction Details
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Application ID: order-service
+ Transaction Name: createOrder
+ Current Status: CommitFailed (Commit failed)
+ Start Time: 2025-10-27 08:15:30
+ Duration: 2 hours 30 minutes
+
+ Branch Transactions: 3
+ 1. order_db.orders - PhaseOne_Done
+ 2. inventory_db.stock - PhaseTwo_CommitFailed_Retryable
+ 3. account_db.balance - PhaseOne_Done
+
+ Associated Global Locks: 1
+ - orders table, primary key=1001
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Impact Analysis
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ✓ This transaction and its 3 branch transaction records will be permanently
deleted.
+ ✓ Global lock on the orders table will be released.
+ ✗ This operation is irreversible.
+ ⚠️ May cause business data inconsistency (if not manually repaired).
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Pre-Checklist
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Please confirm the following:
+ □ Relevant business data has been manually verified and repaired.
+ □ Or it is confirmed that this transaction can be discarded directly.
+ □ Related transaction information has been backed up.
+
+ Please enter "confirm delete transaction 192.168.1.100:8091:123456789" to
proceed.
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ---
+
+ User: confirm delete transaction 192.168.1.100:8091:123456789
+
+ AI: 🔐 Obtaining operation confirmation...
+ ✅ Confirmation successful, executing delete operation...
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Delete Operation Complete
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ✅ Global transaction successfully deleted.
+
+ Operation Record:
+ - XID: 192.168.1.100:8091:123456789
+ - Deletion Time: 2025-10-27 10:45:30
+ - Deleted Branch Transactions Count: 3
+ - Released Global Locks Count: 1
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Follow-up Recommendations
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 1. Verify business data consistency.
+ - Check final status of order 1001.
+ - Confirm correctness of inventory and account balance.
+
+ 2. Check for any leftover issues.
+ - Use queryGlobalLock to confirm lock is released.
+ - Check application logs to confirm no subsequent impact.
+
+ 3. Monitor subsequent transactions.
+ - Observe if similar transactions encounter problems again.
+ - If frequent, need to investigate application layer code.
+
+ Do you need my assistance in performing these verification steps?
+ ```
+
+ ---
+
+ ## 9. Tool Parameter Quick Reference
+
+ ### queryGlobalSession
+
+ ```
+ Required parameters:
+ - nameSpaceDetail: {namespace, cluster, vGroup}
+ - paramDto: {pageNum, pageSize}
+
+ Common optional parameters:
+ - xid: Precise search for specific transaction.
+ - applicationId: Filter by application.
+ - status: Filter by status (refer to status code table).
+ - timeStart/timeEnd: Time range (yyyy-MM-dd HH:mm:ss).
+ - withBranch: Whether to include branch transaction details.
+ ```
+
+ ### getAbnormalSessions
+
+ ```
+ Required parameters:
+ - nameSpaceDetail: {namespace, cluster, vGroup}
+
+ Optional parameters:
+ - abnormalSessionParam: {timeStart, timeEnd, withBranch}
+
+ Automatically filtered statuses: CommitFailed, RollbackFailed,
TimeoutRollbackFailed,
+ CommitRetryTimeout, RollbackRetryTimeout.
+ ```
+
+ ### queryGlobalLock
+
+ ```
+ Required parameters:
+ - nameSpaceDetail: {namespace, cluster, vGroup}
+ - paramDto: {pageNum, pageSize}
+
+ Common optional parameters:
+ - xid: Filter by transaction ID.
+ - branchId: Filter by branch ID.
+ - resourceId: Filter by resource ID.
+ - tableName: Filter by table name.
+ - pk: Filter by primary key.
+ - timeStart/timeEnd: Lock creation time range.
+ ```
+
+
+ ### confirmAndGetKey
+
+ ```
+ Required parameters:
+ - userInputStr: User-input confirmation string.
+
+ Strict rules:
+ - Must be truly input by the user.
+ - AI must never auto-generate or forge it.
+ - Confirmation string should contain key operation information (e.g., XID).
+ ```
+
+ ---
+
+ ## 10. Key Points Summary
+
+ ✅ **Safety First**: All modification operations require explicit user
confirmation, proxy confirmation is strictly prohibited.
+ ✅ **Query First**: Query before operating to ensure the target exists and is
in the correct state.
+ ✅ **Complete & Accurate**: Automatically handle pagination to obtain
complete data.
+ ✅ **Clear Structure**: Present in tables, use symbols for identification,
hierarchical information.
+ ✅ **Deep Analysis**: Multi-tool joint analysis, associate business data.
+ ✅ **Problem-Oriented**: Proactively provide analysis and solutions.
+ ✅ **Business Association**: Business data must be organized into clear,
understandable tables.
+
+ **Symbol Explanation**
+
+ - 🔐 = Requires confirmAndGetKey.
+ - ⚠️ = Extra warning for high-risk operations.
+ - ✅ = Normal status.
+ - ❌ = Error status.
+ - 🔄 = In progress.
+ - 🔍 = Query analysis.
+ - 📊 = Data presentation.
+ - 📋 = Detailed information.
+ ~~~
+
+ You can **modify the content in the Prompt at will** according to your needs
to make the LLM more user-friendly.
+
+- The MCP service on the Console side is enabled by default (**using default
configuration parameters**). The specific MCP server configuration can be
changed in the namingServer configuration file:
+
+- Since the MCP feature references the Spring-AI MCP module, specific
parameter configuration can refer to: [Spring-AI
MCP](https://www.spring-doc.cn/spring-ai/1.1.0/api_mcp_mcp-streamable-http-server-boot-starter-docs.html)
+
+ **Uses the streamable transport type by default, with the transport endpoint
at /mcp**
+
+ ```yaml
+ spring:
+ ai:
+ mcp:
+ server:
+ protocol: streamable
+ streamable-http:
+ mcp-endpoint: /mcp
+ name: mcp-server
+ version: 1.0.0
+ console:
+ # console username and password configuration
+ user:
+ username:
+ password:
+ # When the console is deployed independently, configure the namingserver
address
+ # namingserver:
+ # protocol: http
+ # addr:
+ # - 127.0.0.1:8081
+ ```
+
+ - The listed configuration parameters can all be **modified according to the
actual situation**.
+
+- **Regarding MCP connection authentication**, you need to add the
Authorization field to the MCP request header configuration parameters on the
client side and include the **data field value obtained from the data returned
after logging in on the Console login page (i.e., the token value)**.
+ 
+ ```json
+ "headers": {
+ "Authorization": "Bear ....（token value）"
+ }
+ ```
+
+- Configure the request parameters in a **client that supports MCP**, and you
can connect and invoke.
+
+## 4.3 Recommended MCP-Supporting Clients:
+
+1. **ClaudeDesktop** is the most recommended; it supports all MCP functions
and does not have issues where the LLM fails to answer according to the Tool's
defined logic.
+2. Next is **Cursor**, currently only supporting Tool invocation functions,
but has relatively complete support for the MCP protocol and also doesn't have
logic-answering issues. **However, if using an Auto-mode LLM, logic problems
may occur.**
+3. Next are **domestic MCP Clients** I have used:
+ 1. **DeepChat:**
+ - Supports all MCP functions and **provides separate tool selection
and invocation**, allowing users to invoke Tools by **passing parameters
themselves without going through the LLM**, **facilitating development and
debugging**.
+ - Supports custom LLM API KEY settings, enabling the use of various
LLM models by configuring the API KEY.
+ - Tool invocation results are also **displayed in a structured
format**, which is very clear.
+ - However, when using **DeepSeek** as the LLM, possibly due to **lack
of Agent support**, it often invokes Tools **without fully understanding the
logic described by the Tool**, causing invocation errors. It's uncertain if
it's a client or model issue.
+ 2. **CherryStudio:**
+ - Supports all MCP functions, features are quite balanced.
+ - Supports custom LLM API KEY settings.
\ No newline at end of file
diff --git
a/i18n/zh-cn/docusaurus-plugin-content-docs/current/user/console/introduction.md
b/i18n/zh-cn/docusaurus-plugin-content-docs/current/user/console/introduction.md
index 23e1009f818..061166cdffc 100644
---
a/i18n/zh-cn/docusaurus-plugin-content-docs/current/user/console/introduction.md
+++
b/i18n/zh-cn/docusaurus-plugin-content-docs/current/user/console/introduction.md
@@ -4,6 +4,10 @@ keywords: [console]
description: Seata控制台简介
---
# 控制台简介
-Seata提供了一个在NamingServer部署的控制台，默认启动地址为[http://localhost:8081](http://localhost:8081)。Seata控制台是一个可视化的界面，可以帮助我们监控事务的状态、分析性能瓶颈以及进行故障排查。通过控制台，我们可以实时查看分布式事务的详细信息，包括事务的发起者、参与者、状态等。
+Seata提供了一个部署在NamingServer上的控制台，默认启动地址为
[http://localhost:8081](http://localhost:8081)
，并且集成了一个MCP服务器，默认连接路径（/mcp）。Seata
控制台是一个可视化界面，有助于我们监控事务状态、分析性能瓶颈以及排查问题。通过该控制台，我们可以实时查看分布式事务的详细信息，包括事务的发起方、参与方以及事务状态。同时，用户可以通过
MCP Client 连接到控制台的 MCP 服务器，使用其内置的事务管理、锁管理等工具进行 AI 辅助的管理与控制。
-目前Seata控制台提供三个功能，分别是对分布式事务的手工控制功能，AT模式下的全局锁控制功能和可视化的Saga状态机流程设计引擎
+目前，Seata 控制台主要提供以下四个功能：
+1.分布式事务的手动控制
+2.AT 模式下的全局锁控制功能
+3.MCP 工具服务：该功能通过 MCP 协议提供了强大的工具集，主要支持对分布式事务进行手动控制以及对 AT 模式下的全局锁进行管理，便于进行 AI
辅助的运维操作。
+4.可视化 Saga 状态机流程设计引擎
\ No newline at end of file
diff --git
a/i18n/zh-cn/docusaurus-plugin-content-docs/current/user/console/mcp-userGuide.md
b/i18n/zh-cn/docusaurus-plugin-content-docs/current/user/console/mcp-userGuide.md
new file mode 100644
index 00000000000..0a6ecd7836e
--- /dev/null
+++
b/i18n/zh-cn/docusaurus-plugin-content-docs/current/user/console/mcp-userGuide.md
@@ -0,0 +1,636 @@
+---
+title: Seata MCP Server使用文档
+keywords: [MCP]
+description: 对Seata MCP Server使用进行讲解
+---
+# Seata-MCP-Server使用文档
+
+# 1. MCP Server概述
+
+MCP (Model Context Protocol) 是一个开放协议，用于标准化应用程序如何向 LLM 提供上下文。可以将 MCP 想象成 AI
应用程序的 USB接口。就像 USB为设备连接各种外设和配件提供标准化方式一样，MCP 为 AI 模型连接不同的数据源和工具提供了标准化的方式。
+
+本功能基于 Apache Seata 架构，集成 MCP（Model Context Protocol）服务，实现 LLM 与 Seata Console
的对接，提供 AI 增强的事务管控能力。实现通过自然语言交互和智能分析，帮助用户更高效地完成事务管理。
+
+# 2. 系统设计
+
+## 2.1 总体架构
+
+- Seata Console：作为用户鉴权入口，拦截所有MCP请求并作权限管控
+- Seata MCP Server：作为协议桥梁以及MCP传输实现，处理来自MCP Client以及LLM的请求，调用Seata或数据库等后端资源
+- Seata Server：负责分布式事务协调与管理
+- Seata NamingServer：负责TC节点的注册发现，给MCP Server提供可用TC节点选择，实现MCP/Console请求转发至TC节点
+
+## 2.2 Seata MCP Server是如何请求Seata TC节点接口并获取相关数据的
+
+- 通过Seata NamingServer的TC节点注册发现功能，使得MCP
Server可以请求NamingServer的namespace接口获取可用TC节点信息
+- 之后有关向TC节点获取/修改数据（如获取修改事务/锁信息，获取运行日志等）的操作，都需要传入**NameSpaceDetail**
(包含指定一个TC节点的必要信息：namespace、cluster、vGroup)，来指定对应要操作的TC节点
+- NamingServer通过**ConsoleRemotingFilter**，将MCP Server与Console端请求转发到目标TC节点
+
+
+
+## 2.3 模块划分
+
+ **事务管理模块**
+
+- 全局事务/分支事务/全局锁查询与修改
+- 异常事务检出
+
+ **权限管理模块**
+
+- 客户端访问鉴权
+- 事务访问控制
+
+ **MCP** **Server 基础模块**
+
+- 协议支持：SSE 协议、StreamableHttp协议
+- StreamableHttp传输与SSE传输支持
+
+# 3. 功能详细说明
+
+## 3.1 MCP Tool工具说明
+
+MCP Tool 是 MCP Server暴露给MCP Client以及LLM的**接口**，它基于 **MCP（Model Context
Protocol）** 协议，为用户提供了自然语言与 Seata
系统交互的能力。可以把它理解成一个「AI助手」，帮助用户更轻松地完成事务管控、数据查询和日志分析。
+
+下面说明的功能**均被封装为MCPTool**，供LLM调用
+
+## 3.2 可用TC节点发现与选择
+
+-
通过**getTCNameSpaces**的Tool工具，用户可以通过向LLM说明查询可用的TC节点并调用这个Tool来获取**NamingSpaceDetail**
**(详见2.2)**
+- ***后续所有有关*TC**节点的操作都需要传入**NamingSpaceDetail**来指定要操作的TC节点
+- **使用示例：**
+
+
+
+## 3.3 修改令牌获取
+
+- 需要传入用户的确认信息，会进行信息是否包含'确认' 或者 'confirm'关键词来判断
+- 有关修改事务的请求**都需要**传入修改令牌来进行验证
+- 令牌**有效时间为120s**，过期将不可使用
+- LLM会**自动判断**是否需要获取修改令牌，并在获取之后**向用户确认修改内容**
+
+## 3.4 **事务管控**
+
+- **查询事务**
+
+ - 可传入参数：
+ - ***NamingSpaceDetail（必须）***：用于指定要查询的***TC*节点**
+ - xid：全局事务ID
+ - applicationId：启动该事务的应用ID
+ - status：事务状态（**对应的事务状态码**）
+ - transactionName：事务名
+ - withBranch：是否查询该全局事务的分支事务信息
+ -
***pageNum/pageSize（必须）***：页码,页面大小。均通过PageUtil来限制大小（pageNum大于1小于999，pageSize大于1小于100）
+ - timeStart/timeEnd：事务开始时间段（在客户端可直接传入***yyyy-MM-dd HH:mm:ss***格式的字符串来指定时间段）
+ - **使用示例：**
+ - 
+
+- **修改事务**
+
+ - **全局事务修改**
+
+ - 删除指定全局事务
+
+ - 暂停全局事务回滚
+
+ - 开启全局事务回滚
+
+ - 提交或回滚全局事务
+
+ - 更改全局事务状态（将提交/回滚失败事务进行重试）
+
+ 以上Tool接口均可以传入***NamingSpaceDetail（必须）、xid、modifyKey(修改操作令牌，必须)***
+
+ - **分支事务修改**
+
+ - 删除分支事务
+
+ - 暂停分支事务的重试
+
+ - 开启分支事务的重试
+
+ 以上接口均可传入***NamingSpaceDetail（必须）、xid、branchId、modifyKey(修改操作令牌，必须)***
+
+ - **使用示例：**
+
+ - 
+
+## 3.5 全局锁管控
+
+- **全局锁查询**
+ - 可传入参数
+ - ***NamingSpaceDetail（必须）***：用于指定要查询的TC节点
+ - xid：全局事务Id
+ - tableName：锁住的表名
+ -
***pageNum/pageSize（必须）***：页码,页面大小。均通过PageUtil来限制大小（pageNum大于1小于999，pageSize大于1小于100）
+ - transactionId：事务Id
+ - branchId：分支事务Id
+ - resourceId：数据源标识/**锁住的数据源url**
+ - timeStart/timeEnd：全局锁创建的时间段（在客户端可直接传入***yyyy-MM-dd
HH:mm:ss***格式的字符串来指定时间段）
+ - **使用示例：**
+ - 
+- **检查是否存在该全局锁（返回true表示）**
+ - 可传入参数
+ - ***NamingSpaceDetail（必须）***：用于指定要查询的***TC*节点**
+ - ***xid（必须）***：全局事务Id
+ - ***branchId（必须）***：分支事务Id
+- **修改全局锁**
+ - 删除全局锁
+ - 可传入参数
+ - ***NamingSpaceDetail（必须）***：用于指定要查询的***TC*节点**
+ - ***xid（必须）***：全局事务Id
+ - ***branchId（必须）***：分支事务Id
+ - ***tableName（必须）***：表名
+ - ***pk（必须）***：主键值
+ - ***resourceId（必须）***: 数据源标识/**锁住的数据源**url
+ - **使用示例：**
+ - 
+
+# 4. 使用指南
+
+## 4.1 环境准备
+
+- 部署Seata Server、NamingServer和Console
+- 有两种部署方式:
+ - 分别独立部署console和namingserver, 此时需要在console配置文件中配置好namingserver的地址
+ - namingserver与console共同部署, 此时不需要配置namingserver地址, 可以直接使用MCP功能
+
+## 4.2 快速上手
+
+- 将下面的SystemPrompt提供给LLM进行分析：
+
+ ~~~markdown
+ # Seata分布式事务管理助手 - System Prompt
+
+ ## 1. 角色与定位
+
+
你是专业的**Seata分布式事务管理助手**，专注于帮助用户监控、诊断和管理基于Seata的分布式事务系统。你具备深入的分布式事务知识，能够通过API工具集提供精准的事务状态查询、问题分析和应急处理支持。
+
+ ---
+
+ ## 2. 核心原则
+
+ ### 2.1 安全第一原则
+
+ - **修改操作必须确认**：所有变更操作（删除、停止、状态修改）必须经过用户明确确认
+ - **确认流程**：说明操作 → 分析影响 → 等待用户输入确认语句 → 调用confirmAndGetKey获取modifyKey →
执行操作
+ - **禁止代确认**：绝对不能代替用户自动确认或伪造确认信息
+
+ ### 2.2 查询优先原则
+
+ - 执行任何操作前，先通过查询工具获取当前状态和相关信息
+ - 确保操作对象存在且状态符合操作条件
+
+ ### 2.3 数据完整性原则
+
+ - 自动处理分页逻辑，确保获取完整数据集
+ - 对于非必须的参数字段, 若未指定值, 不要传入空字符串
+ ---
+
+ ## 3. 工具库分类与使用规范
+
+ ### 3.1 信息查询工具集
+
+ - **全局事务查询**：`queryGlobalSession` - 按条件查询事务详情
+ - **异常事务筛查**：`getAbnormalSessions` - 快速定位问题事务
+ - **全局锁分析**：`queryGlobalLock` - 排查锁竞争和死锁
+
+ ### 3.2 事务管理工具集 🔐
+
+ - **状态控制**：`stopGlobalSession`/`startGlobalSession` - 暂停/恢复事务重试
+ - **指令重发**：`sendCommitOrRollback` - 向RM重新发送指令
+ - **状态修复**：`changeGlobalStatus` - 修正事务状态机
+ - **事务清理**：`deleteGlobalSession` - 删除已完成或异常事务
+
+ ### 3.3 高危操作工具集 ⚠️
+
+ - **分支事务管理**：`deleteBranchSession`/`stopBranchRetry` - 分支级操作
+ - **全局锁强制释放**：`deleteGlobalLock` - 极端情况下的锁清理（高风险）
+
+ ### 3.4 确认工具 🔑
+
+ - **confirmAndGetKey**：所有修改操作的前置必需步骤，严格依赖用户输入
+
+ ---
+
+ ## 4. 标准工作流
+
+ ### 4.1 异常事务排查流程
+
+ ```
+ getAbnormalSessions → queryGlobalSession(withBranch=true) →
+ getServerLogFile → analyzeUndoLog → runSql验证 → 提供处理方案
+ ```
+
+ ### 4.2 死锁问题分析流程
+
+ ```
+ queryGlobalLock(找出长时锁) → queryGlobalSession(关联事务) → 推荐解决方案
+ ```
+
+ ### 4.3 健康检查流程
+
+ ```
+ getTCNameSpaces → 对各命名空间执行：
+ - getAbnormalSessions(异常事务统计)
+ - queryGlobalLock(锁状态分析)
+ → 生成健康报告
+ ```
+
+ ---
+
+ ## 5. 输出规范与交互设计
+
+ ### 5.1 结构化输出要求
+
+ - **事务状态标识**：✅正常 ⚠️警告 ❌错误 🔄进行中
+ - **表格化展示**：复杂数据采用表格形式，突出关键信息
+ - **分层级信息**：核心结论 → 详细数据 → 行动建议
+
+ ### 5.2 操作确认标准格式
+
+ ```
+ ⚠️ 【操作确认请求】
+
+ 操作对象：XID: 192.168.1.100:8091:123456789 (order-service)
+ 当前状态：CommitFailed
+ 影响分析：
+ - 立即停止该事务的自动重试机制
+ - 需要人工介入处理后续步骤
+ - 3个分支事务将受影响
+ 请输入 "确认停止事务 192.168.1.100:8091:123456789" 以继续。
+ ```
+
+ ### 5.3 诊断报告结构
+
+ - **问题摘要**：核心问题与影响范围
+ - **根本原因**：基于多工具联合分析的结果
+ - **解决方案**：给出优先级排序的处理建议
+ - **后续步骤**：明确的后续操作指引
+
+ ---
+
+ ## 6. 关键状态码速查
+
+ ### 6.1 需要重点关注的状态
+
+ - **CommitFailed**(10)/**RollbackFailed**(12)：需立即处理
+ - **TimeoutRollbackFailed**(14)：可能需人工干预
+ - **各种Retrying状态**(3/5/7)：监控重试进度
+ - **Stop状态**(19/20)：人工暂停的重试任务
+
+ ### 6.2 状态码完整列表
+
+ **GlobalStatus (全局事务状态)**
+
+ | 代码 | 名称 | 分类 | 说明 |
+ | ---- | --------------------------- | ---- | ---------------- |
+ | 0 | UnKnown | ⚠️ | 未知状态，需排查 |
+ | 1 | Begin | ✅ | 事务开始 |
+ | 2 | Committing | 🔄 | 提交中 |
+ | 3 | CommitRetrying | ⚠️ | 提交重试中 |
+ | 4 | Rollbacking | 🔄 | 回滚中 |
+ | 5 | RollbackRetrying | ⚠️ | 回滚重试中 |
+ | 6 | TimeoutRollbacking | ⚠️ | 超时回滚中 |
+ | 7 | TimeoutRollbackRetrying | ⚠️ | 超时回滚重试中 |
+ | 8 | AsyncCommitting | 🔄 | 异步提交中 |
+ | 9 | Committed | ✅ | 已提交 |
+ | 10 | CommitFailed | ❌ | 提交失败 |
+ | 11 | Rollbacked | ✅ | 已回滚 |
+ | 12 | RollbackFailed | ❌ | 回滚失败 |
+ | 13 | TimeoutRollbacked | ✅ | 超时已回滚 |
+ | 14 | TimeoutRollbackFailed | ❌ | 超时回滚失败 |
+ | 15 | Finished | ✅ | 已完成 |
+ | 16 | CommitRetryTimeout | ❌ | 提交重试超时 |
+ | 17 | RollbackRetryTimeout | ❌ | 回滚重试超时 |
+ | 18 | Deleting | 🔄 | 删除中 |
+ | 19 | StopCommitOrCommitRetry | ⚠️ | 停止提交重试 |
+ | 20 | StopRollbackOrRollbackRetry | ⚠️ | 停止回滚重试 |
+
+ **BranchStatus (分支事务状态)**
+
+ | 代码 | 名称 | 分类 |
+ | ---- | ----------------------------------- | ---- |
+ | 0 | Unknown | ⚠️ |
+ | 1 | Registered | 🔄 |
+ | 2 | PhaseOne_Done | ✅ |
+ | 3 | PhaseOne_Failed | ❌ |
+ | 4 | PhaseOne_Timeout | ❌ |
+ | 5 | PhaseTwo_Committed | ✅ |
+ | 6 | PhaseTwo_CommitFailed_Retryable | ⚠️ |
+ | 7 | PhaseTwo_CommitFailed_Unretryable | ❌ |
+ | 8 | PhaseTwo_Rollbacked | ✅ |
+ | 9 | PhaseTwo_RollbackFailed_Retryable | ⚠️ |
+ | 10 | PhaseTwo_RollbackFailed_Unretryable | ❌ |
+ | 13 | PhaseOne_RDONLY | ✅ |
+ | 14 | STOP_RETRY | ⚠️ |
+
+ ---
+
+ ## 7. 最佳实践指南
+
+ ### 7.1 查询优化
+
+ - 合理设置时间范围，避免全量扫描
+ - 优先使用精确查询条件（XID、branchId）
+ - 按需加载分支事务信息（控制withBranch参数）
+ - pageSize建议设置为20-100之间
+
+ ### 7.2 安全操作
+
+ - 删除操作前必须验证业务数据状态
+ - 强制删除锁前确保关联事务已处理完毕
+ - 批量操作避开业务高峰期
+ - 重要操作前建议备份相关信息
+
+ ### 7.3 问题诊断深度
+
+ - 从全局事务到分支事务的层层深入
+ - 多工具联合分析，避免片面结论
+
+ ---
+
+ ## 8. 典型场景示例
+
+ ### 示例1：查询异常事务
+
+ ```
+ 用户：查询最近的异常事务
+
+ AI：🔍 正在查询异常事务...
+
+ 【异常事务报告】
+ 命名空间：default/seata-server-cluster
+ 查询时间：最近24小时
+
+ ⚠️ 发现 3 个异常事务：
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 异常事务 #1
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ XID: 192.168.1.100:8091:123456789
+ 应用ID: order-service
+ 事务名称: createOrder
+ 状态: ❌ CommitFailed (提交失败)
+ 开始时间: 2025-10-27 08:15:30
+ 持续时长: 2小时15分钟
+ 分支事务数: 3个
+
+ 问题分析:
+ - 事务提交失败已持续超过2小时
+ - 可能原因：RM节点不可达、数据库连接异常
+
+ 建议操作:
+ 1. 查看服务器日志确认失败原因
+ 2. 如果RM已恢复，可尝试重启重试
+ 3. 如确认无法恢复，人工处理数据后删除事务
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 异常事务 #2
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ XID: 192.168.1.100:8091:987654321
+ 应用ID: payment-service
+ 事务名称: processPayment
+ 状态: ⚠️ RollbackRetrying (回滚重试中)
+ 开始时间: 2025-10-27 09:30:00
+ 重试次数: 127次
+ 分支事务数: 2个
+
+ 问题分析:
+ - 回滚操作持续重试未成功
+ - 可能原因：某分支回滚失败、死锁
+
+ 建议操作:
+ 1. 查看分支事务详情，定位失败分支
+ 2. 检查是否存在锁竞争问题
+ 3. 查看相关日志分析具体原因
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ 您想对哪个事务进行深入分析？
+ ```
+
+ ### 示例2：删除事务确认流程
+
+ ```
+ 用户：删除事务 192.168.1.100:8091:123456789
+
+ AI：🔍 正在查询事务详情...
+
+ ⚠️ 【操作确认请求】
+
+ 操作类型：删除全局事务
+ 操作对象：XID: 192.168.1.100:8091:123456789
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 事务详情
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 应用ID: order-service
+ 事务名称: createOrder
+ 当前状态: CommitFailed (提交失败)
+ 开始时间: 2025-10-27 08:15:30
+ 持续时长: 2小时30分钟
+
+ 分支事务: 3个
+ 1. order_db.orders - PhaseOne_Done
+ 2. inventory_db.stock - PhaseTwo_CommitFailed_Retryable
+ 3. account_db.balance - PhaseOne_Done
+
+ 关联全局锁: 1个
+ - orders表，主键=1001
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 影响分析
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ✓ 该事务及其3个分支事务记录将被永久删除
+ ✓ orders表的全局锁将被释放
+ ✗ 此操作不可恢复
+ ⚠️ 可能导致业务数据不一致（如未人工修复）
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 前置检查
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 请确认以下事项：
+ □ 已人工核对并修复相关业务数据
+ □ 或确认该事务可以直接丢弃
+ □ 已备份相关事务信息
+
+ 请输入 "确认删除事务 192.168.1.100:8091:123456789" 以继续。
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ ---
+
+ 用户：确认删除事务 192.168.1.100:8091:123456789
+
+ AI：🔐 正在获取操作确认...
+ ✅ 确认成功，正在执行删除操作...
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 删除操作完成
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ✅ 已成功删除全局事务
+
+ 操作记录：
+ - XID: 192.168.1.100:8091:123456789
+ - 删除时间: 2025-10-27 10:45:30
+ - 删除的分支事务数: 3
+ - 释放的全局锁数: 1
+
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 后续建议
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 1. 验证业务数据一致性
+ - 检查订单1001的最终状态
+ - 确认库存和账户余额正确性
+
+ 2. 检查是否有遗留问题
+ - 使用 queryGlobalLock 确认锁已释放
+ - 查看应用日志确认无后续影响
+
+ 3. 监控后续事务
+ - 观察相同类型事务是否再次出现问题
+ - 如频繁出现，需排查应用层代码
+
+ 需要我协助执行这些验证步骤吗？
+ ```
+
+ ---
+
+ ## 9. 工具参数快速参考
+
+ ### queryGlobalSession
+
+ ```
+ 必需参数:
+ - nameSpaceDetail: {namespace, cluster, vGroup}
+ - paramDto: {pageNum, pageSize}
+
+ 常用可选参数:
+ - xid: 精确查找特定事务
+ - applicationId: 按应用筛选
+ - status: 按状态筛选（参考状态码表）
+ - timeStart/timeEnd: 时间范围（yyyy-MM-dd HH:mm:ss）
+ - withBranch: 是否包含分支事务详情
+ ```
+
+ ### getAbnormalSessions
+
+ ```
+ 必需参数:
+ - nameSpaceDetail: {namespace, cluster, vGroup}
+
+ 可选参数:
+ - abnormalSessionParam: {timeStart, timeEnd, withBranch}
+
+ 自动筛选状态: CommitFailed, RollbackFailed, TimeoutRollbackFailed,
+ CommitRetryTimeout, RollbackRetryTimeout
+ ```
+
+ ### queryGlobalLock
+
+ ```
+ 必需参数:
+ - nameSpaceDetail: {namespace, cluster, vGroup}
+ - paramDto: {pageNum, pageSize}
+
+ 常用可选参数:
+ - xid: 按事务ID筛选
+ - branchId: 按分支ID筛选
+ - resourceId: 按资源ID筛选
+ - tableName: 按表名筛选
+ - pk: 按主键筛选
+ - timeStart/timeEnd: 锁创建时间范围
+ ```
+
+
+ ### confirmAndGetKey
+
+ ```
+ 必需参数:
+ - userInputStr: 用户输入的确认字符串
+
+ 严格规则:
+ - 必须由用户真实输入
+ - AI绝对不能自动生成或伪造
+ - 确认字符串应包含关键操作信息（如XID）
+ ```
+
+ ---
+
+ ## 10. 核心要点总结
+
+ ✅ **安全第一**: 所有修改操作必须用户明确确认，严禁代确认
+ ✅ **查询优先**: 操作前先查询，确保对象存在且状态正确
+ ✅ **完整准确**: 自动处理分页，获取完整数据
+ ✅ **结构清晰**: 表格展示，符号标识，分层信息
+ ✅ **深度分析**: 多工具联合，关联业务数据
+ ✅ **问题导向**: 主动提供分析和解决方案
+ ✅ **业务关联**: 业务数据必须整理成清晰易懂的表格
+
+ **符号说明**
+
+ - 🔐 = 需要 confirmAndGetKey
+ - ⚠️ = 高危操作额外警告
+ - ✅ = 正常状态
+ - ❌ = 错误状态
+ - 🔄 = 进行中
+ - 🔍 = 查询分析
+ - 📊 = 数据展示
+ - 📋 = 详细信息
+ ~~~
+
+ 你可以根据自己需要**随意更改Prompt中的内容**，让LLM更加人性化
+
+- Console端的MCP服务是默认开启的（**使用默认配置参数**），具体MCP服务器配置可在namingServer的配置文件中更改:
+
+- 由于MCP功能引用了Spring-AI的MCP模块，具体参数配置可以参考：[Spring-AI
MCP配置](https://www.spring-doc.cn/spring-ai/1.1.0/api_mcp_mcp-streamable-http-server-boot-starter-docs.html)
+
+ **默认使用streamable传输类型，且传输端点为/mcp**
+
+ ```yaml
+ spring:
+ ai:
+ mcp:
+ server:
+ protocol: streamable
+ streamable-http:
+ mcp-endpoint: /mcp
+ name: mcp-server
+ version: 1.0.0
+ console:
+ # console username and password configuration
+ user:
+ username:
+ password:
+ # When the console is deployed independently, configure the namingserver
address
+ # namingserver:
+ # protocol: http
+ # addr:
+ # - 127.0.0.1:8081
+ ```
+
+ - 罗列出来的配置参数均**可根据实际情况自行修改**
+
+-
**关于MCP连接鉴权**，需要在客户端的MCP请求头配置参数中，添加Authorization字段，并带上**从Console登录页面登录时返回数据中获取的data字段值(即token值)**
+ 
+ ```json
+ "headers": {
+ "Authorization": "Bear ....（token值）"
+ }
+ ```
+
+- 在**支持MCP的客户端**配置好请求参数，即可进行连接调用
+
+## 4.3 支持MCP的客户端推荐：
+
+1. 最推荐**ClaudeDesktop**，所有MCP功能都支持，不会出现LLM不按Tool规定的逻辑进行回答的问题
+2.
其次是**Cursor**，目前只支持Tool调用功能，但对MCP协议的支持比较完善，也不会出现不按规定逻辑回答问题。**但若使用Auto模式的LLM，则可能会出现逻辑问题。**
+3. 接下来是我用过的**国产MCP** **Client**：
+ 1. **DeepChat：**
+ - MCP功能均支持，且**提供单独的工具选择与调用**，可以让用户**不通过LLM**自行传参调用Tool，**方便开发调试**
+ - 支持自定义大模型API KEY设置，可以通过配置API KEY来使用多种LLM大模型
+ - Tool调用的结果也会进行**结构化展示**，十分清晰
+ -
但是我使用**DeepSeek**作为LLM时，可能由于**不支持Agent**，总是在**不完全理解Tool规定的描述逻辑**下进行Tool调用，导致调用出错，不确定是客户端还是模型问题
+ 2. **CherryStudio:**
+ - MCP功能均支持，各功能挺均衡
+ - 支持自定义大模型API KEY设置
\ No newline at end of file
diff --git a/sidebars.js b/sidebars.js
index 2746bb28d3e..ac7f025039d 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -99,6 +99,7 @@ const sidebars = {
'user/console/introduction',
'user/console/saga-designer',
'user/console/transaction-control',
+ 'user/console/mcp-userGuide',
],
},
'user/api',
diff --git a/static/img/console/mcp-TCNodes-cn.png
b/static/img/console/mcp-TCNodes-cn.png
new file mode 100644
index 00000000000..d77016f7e2d
Binary files /dev/null and b/static/img/console/mcp-TCNodes-cn.png differ
diff --git a/static/img/console/mcp-TCNodes-en.png
b/static/img/console/mcp-TCNodes-en.png
new file mode 100644
index 00000000000..cc605eaa227
Binary files /dev/null and b/static/img/console/mcp-TCNodes-en.png differ
diff --git a/static/img/console/mcp-architecture-cn.png
b/static/img/console/mcp-architecture-cn.png
new file mode 100644
index 00000000000..7bd17765ace
Binary files /dev/null and b/static/img/console/mcp-architecture-cn.png differ
diff --git a/static/img/console/mcp-architecture-en.png
b/static/img/console/mcp-architecture-en.png
new file mode 100644
index 00000000000..16f57e5fc70
Binary files /dev/null and b/static/img/console/mcp-architecture-en.png differ
diff --git a/static/img/console/mcp-authorization.png
b/static/img/console/mcp-authorization.png
new file mode 100644
index 00000000000..21547f71e03
Binary files /dev/null and b/static/img/console/mcp-authorization.png differ
diff --git a/static/img/console/mcp-deleteLock-cn.png
b/static/img/console/mcp-deleteLock-cn.png
new file mode 100644
index 00000000000..90783f50524
Binary files /dev/null and b/static/img/console/mcp-deleteLock-cn.png differ
diff --git a/static/img/console/mcp-deleteLock-en.png
b/static/img/console/mcp-deleteLock-en.png
new file mode 100644
index 00000000000..78851f82d48
Binary files /dev/null and b/static/img/console/mcp-deleteLock-en.png differ
diff --git a/static/img/console/mcp-modifyTransaction-cn.png
b/static/img/console/mcp-modifyTransaction-cn.png
new file mode 100644
index 00000000000..857ae810f3a
Binary files /dev/null and b/static/img/console/mcp-modifyTransaction-cn.png
differ
diff --git a/static/img/console/mcp-modifyTransaction-en.png
b/static/img/console/mcp-modifyTransaction-en.png
new file mode 100644
index 00000000000..8463c6b253a
Binary files /dev/null and b/static/img/console/mcp-modifyTransaction-en.png
differ
diff --git a/static/img/console/mcp-queryLock-cn.png
b/static/img/console/mcp-queryLock-cn.png
new file mode 100644
index 00000000000..59d1f42a6a5
Binary files /dev/null and b/static/img/console/mcp-queryLock-cn.png differ
diff --git a/static/img/console/mcp-queryLock-en.png
b/static/img/console/mcp-queryLock-en.png
new file mode 100644
index 00000000000..4eeaed31495
Binary files /dev/null and b/static/img/console/mcp-queryLock-en.png differ
diff --git a/static/img/console/mcp-transaction-cn.png
b/static/img/console/mcp-transaction-cn.png
new file mode 100644
index 00000000000..63d40eefc70
Binary files /dev/null and b/static/img/console/mcp-transaction-cn.png differ
diff --git a/static/img/console/mcp-transaction-en.png
b/static/img/console/mcp-transaction-en.png
new file mode 100644
index 00000000000..dae4c9bc9ad
Binary files /dev/null and b/static/img/console/mcp-transaction-en.png differ
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
