feat(mcp): enhance MCP tool execution and documentation #330

- Update `execute` method in `CustomMcpServerManager` to return JSON-encoded results.
- Add `commandName` parameter to `ToolchainFunctionProvider` interface and implementations.
- Add new documentation files for MCP client and server usage.
- Remove redundant MCP usage instructions from `mcp.md`.

Author: phodal

core/src/main/kotlin/cc/unitmesh/devti/bridge/archview/ComponentViewFunctionProvider.kt

@@ -6,6 +6,7 @@ import cc.unitmesh.devti.bridge.archview.model.UiComponent
 import cc.unitmesh.devti.bridge.provider.ComponentViewMode
 import cc.unitmesh.devti.provider.toolchain.ToolchainFunctionProvider
 import com.intellij.openapi.project.Project
+import com.intellij.openapi.util.NlsSafe
 
 class ComponentViewFunctionProvider : ToolchainFunctionProvider {
     override fun funcNames(): List<String> = listOf(ArchViewCommand.ComponentView.name)
@@ -16,7 +17,8 @@ class ComponentViewFunctionProvider : ToolchainFunctionProvider {
         project: Project,
         prop: String,
         args: List<Any>,
-        allVariables: Map<String, Any?>
+        allVariables: Map<String, Any?>,
+        commandName: @NlsSafe String
     ): String {
         val uiComponents = ComponentViewProvider.collect(project, ComponentViewMode.DEFAULT)
         val transform = if (prop == "all") {

core/src/main/kotlin/cc/unitmesh/devti/bridge/archview/ContainerViewFunctionProvider.kt

@@ -4,6 +4,7 @@ import cc.unitmesh.devti.bridge.ArchViewCommand
 import cc.unitmesh.devti.provider.toolchain.ToolchainFunctionProvider
 import com.intellij.openapi.module.ModuleManager
 import com.intellij.openapi.project.Project
+import com.intellij.openapi.util.NlsSafe
 
 class ContainerViewFunctionProvider : ToolchainFunctionProvider {
     override fun isApplicable(project: Project, funcName: String) = funcName == ArchViewCommand.ContainerView.name
@@ -14,7 +15,8 @@ class ContainerViewFunctionProvider : ToolchainFunctionProvider {
         project: Project,
         prop: String,
         args: List<Any>,
-        allVariables: Map<String, Any?>
+        allVariables: Map<String, Any?>,
+        commandName: @NlsSafe String
     ): String {
         val modules = ModuleManager.getInstance(project).modules
         return "Here is current project modules:\n```\n" + modules.joinToString("\n") {

core/src/main/kotlin/cc/unitmesh/devti/bridge/assessment/SccFunctionProvider.kt

@@ -7,6 +7,7 @@ import cc.unitmesh.devti.provider.toolchain.ToolchainFunctionProvider
 import com.intellij.openapi.application.ApplicationManager
 import com.intellij.openapi.project.Project
 import com.intellij.openapi.project.guessProjectDir
+import com.intellij.openapi.util.NlsSafe
 
 class SccFunctionProvider : ToolchainFunctionProvider {
     override fun isApplicable(project: Project, funcName: String): Boolean = funcName == Assessment.SCC.name
@@ -17,7 +18,8 @@ class SccFunctionProvider : ToolchainFunctionProvider {
         project: Project,
         prop: String,
         args: List<Any>,
-        allVariables: Map<String, Any?>
+        allVariables: Map<String, Any?>,
+        commandName: @NlsSafe String
     ): Any {
         val baseDir = project.guessProjectDir()!!.path
         val path = if (prop.isEmpty()) { baseDir } else "$baseDir/$prop"

core/src/main/kotlin/cc/unitmesh/devti/bridge/knowledge/HistoryFunctionProvider.kt

@@ -5,6 +5,7 @@ import cc.unitmesh.devti.provider.RevisionProvider
 import cc.unitmesh.devti.provider.toolchain.ToolchainFunctionProvider
 import com.intellij.openapi.project.Project
 import com.intellij.openapi.project.guessProjectDir
+import com.intellij.openapi.util.NlsSafe
 import com.intellij.openapi.vfs.VirtualFile
 import com.intellij.openapi.vfs.VirtualFileManager
 
@@ -17,7 +18,8 @@ class HistoryFunctionProvider : ToolchainFunctionProvider {
         project: Project,
         prop: String,
         args: List<Any>,
-        allVariables: Map<String, Any?>
+        allVariables: Map<String, Any?>,
+        commandName: @NlsSafe String
     ): Any {
         val path = project.lookupFile(prop) ?: return "File not found"
         return RevisionProvider.provide()?.let {

core/src/main/kotlin/cc/unitmesh/devti/bridge/knowledge/KnowledgeFunctionProvider.kt

@@ -9,6 +9,7 @@ import cc.unitmesh.devti.util.relativePath
 import com.intellij.lang.LanguageCommenters
 import com.intellij.openapi.application.runReadAction
 import com.intellij.openapi.project.Project
+import com.intellij.openapi.util.NlsSafe
 import com.intellij.psi.PsiElement
 import com.intellij.psi.PsiManager
 
@@ -53,7 +54,8 @@ class KnowledgeFunctionProvider : ToolchainFunctionProvider {
         project: Project,
         prop: String,
         args: List<Any>,
-        allVariables: Map<String, Any?>
+        allVariables: Map<String, Any?>,
+        commandName: @NlsSafe String
     ): Any {
         val split = prop.split("#")
         if (split.size != 2) {

core/src/main/kotlin/cc/unitmesh/devti/devin/dataprovider/BuiltinCommand.kt

@@ -149,6 +149,12 @@ enum class BuiltinCommand(
                     return TOOLCHAIN_COMMAND
                 }
 
+                ToolchainFunctionProvider.all().forEach {
+                    if (it.funcNames().contains(commandName)) {
+                        return TOOLCHAIN_COMMAND
+                    }
+                }
+
                 val project = ProjectManager.getInstance().openProjects.first()
                 AutoDevNotifications.warn(project, "Command not found: $commandName")
                 return null

core/src/main/kotlin/cc/unitmesh/devti/mcp/CustomMcpServerManager.kt

@@ -4,20 +4,19 @@ import cc.unitmesh.devti.settings.customize.customizeSetting
 import com.intellij.openapi.components.Service
 import com.intellij.openapi.diagnostic.logger
 import com.intellij.openapi.project.Project
-import kotlinx.serialization.Serializable
-import kotlinx.serialization.json.Json
-import io.modelcontextprotocol.kotlin.sdk.client.Client
 import io.modelcontextprotocol.kotlin.sdk.Implementation
 import io.modelcontextprotocol.kotlin.sdk.Tool
+import io.modelcontextprotocol.kotlin.sdk.client.Client
 import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport
 import kotlinx.io.asSink
 import kotlinx.io.asSource
 import kotlinx.io.buffered
-import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.jsonObject
 import java.util.concurrent.CompletableFuture
-import kotlin.text.get
 
 @Serializable
 data class McpConfig(
@@ -123,9 +122,9 @@ class CustomMcpServerManager(val project: Project) {
         return tools
     }
 
-    fun execute(project: Project, tool: Tool, map: String): Any {
+    fun execute(project: Project, tool: Tool, map: String): String {
         toolClientMap[tool]?.let {
-            val future = CompletableFuture<Any>()
+            val future = CompletableFuture<String>()
             kotlinx.coroutines.runBlocking {
                 try {
                     val arguments = try {
@@ -136,7 +135,11 @@ class CustomMcpServerManager(val project: Project) {
                     }
 
                     val result = it.callTool(tool.name, arguments, true, null)
-                    future.complete(result)
+                        if (result?.content.isNullOrEmpty()) {
+                            future.complete("No result from tool ${tool.name}")
+                        } else {
+                            future.complete(Json.encodeToString(result.content))
+                        }
                 } catch (e: Error) {
                     logger<CustomMcpServerManager>().warn("Failed to execute tool ${tool.name}: $e")
                     future.complete("Failed to execute tool ${tool.name}: $e")

core/src/main/kotlin/cc/unitmesh/devti/mcp/provider/McpFunctionProvider.kt

@@ -5,6 +5,7 @@ import cc.unitmesh.devti.mcp.CustomMcpServerManager
 import cc.unitmesh.devti.provider.toolchain.ToolchainFunctionProvider
 import com.intellij.openapi.project.Project
 import com.intellij.openapi.project.ProjectManager
+import com.intellij.openapi.util.NlsSafe
 import io.modelcontextprotocol.kotlin.sdk.Tool.Input
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.encodeToString
@@ -37,11 +38,12 @@ class McpFunctionProvider : ToolchainFunctionProvider {
         project: Project,
         prop: String,
         args: List<Any>,
-        allVariables: Map<String, Any?>
+        allVariables: Map<String, Any?>,
+        commandName: @NlsSafe String
     ): Any {
-        val tool = CustomMcpServerManager.instance(project).collectServerInfos().firstOrNull { it.name == prop }
+        val tool = CustomMcpServerManager.instance(project).collectServerInfos().firstOrNull { it.name == commandName }
         if (tool == null) {
-            return "No such tool: $prop"
+            return "No MCP such tool: $prop"
         }
 
         return CustomMcpServerManager.instance(project).execute(project, tool, args.firstOrNull().toString())

core/src/main/kotlin/cc/unitmesh/devti/provider/toolchain/ToolchainFunctionProvider.kt

@@ -3,6 +3,7 @@ package cc.unitmesh.devti.provider.toolchain
 import cc.unitmesh.devti.agenttool.AgentTool
 import com.intellij.openapi.extensions.ExtensionPointName
 import com.intellij.openapi.project.Project
+import com.intellij.openapi.util.NlsSafe
 
 interface ToolchainFunctionProvider {
     fun toolInfos(): List<AgentTool> = emptyList()
@@ -11,7 +12,7 @@ interface ToolchainFunctionProvider {
 
     fun isApplicable(project: Project, funcName: String): Boolean
 
-    fun execute(project: Project, prop: String, args: List<Any>, allVariables: Map<String, Any?>): Any
+    fun execute(project: Project, prop: String, args: List<Any>, allVariables: Map<String, Any?>, commandName: String): Any
 
     companion object {
         private val EP_NAME: ExtensionPointName<ToolchainFunctionProvider> =

docs/mcp/mcp-client.md

@@ -0,0 +1,30 @@
+---
+layout: default
+title: AutoDev as MCP Client
+nav_order: 2
+parent: MCP
+---
+
+
+## How to use
+
+1. Enable the MCP server in AutoDev settings
+2. Use the MCP client to connect to the AutoDev server (We use JetBrains MCP Proxy Server to keep same protocol)
+
+```json
+{
+  "mcpServers": {
+    "AutoDev": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@jetbrains/mcp-proxy"
+      ],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+

docs/mcp/mcp-server.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: AutoDev as MCP Server
+nav_order: 3
+parent: MCP
+---
+
+
+The MCP will be convert to DevIns instruction like
+
+    /list_directory
+    ```json
+    {
+     "path": "/Users/phodal/Downloads"
+    }
+    ```

docs/mcp/mcp.md

@@ -19,28 +19,3 @@ This document will discuss the implementation details.
 Requirements: Install Node.js with Npx
 
 - https://nodejs.org/en/download/package-manager
-
-## How to use
-
-1. Enable the MCP server in AutoDev settings
-2. Use the MCP client to connect to the AutoDev server (We use JetBrains MCP Proxy Server to keep same protocol)
-
-```json
-{
-  "mcpServers": {
-    "AutoDev": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@jetbrains/mcp-proxy"
-      ],
-      "disabled": false,
-      "autoApprove": []
-    }
-  }
-}
-```
-
-## Supported Action (Todo)
-
-

exts/devins-lang/src/main/kotlin/cc/unitmesh/devti/language/compiler/DevInsCompiler.kt

@@ -298,7 +298,14 @@ class DevInsCompiler(
                     if (provider != null) {
                         executeExtensionFunction(used, prop, provider)
                     } else {
-                        PrintInsCommand("/" + commandNode.commandName + ":" + prop)
+                        var cmd = PrintInsCommand("/" + commandNode.commandName + ":" + prop)
+                        ToolchainFunctionProvider.all().forEach {
+                            if (it.funcNames().contains(originCmdName)) {
+                                cmd = executeExtensionFunction(used, prop, it)
+                            }
+                        }
+
+                        cmd
                     }
                 } catch (e: Exception) {
                     PrintInsCommand("/" + commandNode.commandName + ":" + prop)
@@ -351,7 +358,8 @@ class DevInsCompiler(
         val task = object : Task.Backgroundable(myProject, "Processing context", false) {
             override fun run(indicator: ProgressIndicator) {
                 val result = try {
-                    provider.execute(myProject!!, prop, args, emptyMap())
+                    val cmd = runReadAction { used.text.removePrefix("/") }
+                    provider.execute(myProject!!, prop, args, emptyMap(), cmd)
                 } catch (e: Exception) {
                     logger<DevInsCompiler>().warn(e)
                     val text = runReadAction { used.text }

exts/devins-lang/src/main/kotlin/cc/unitmesh/devti/language/compiler/exec/DatabaseInsCommand.kt

@@ -25,7 +25,7 @@ class DatabaseInsCommand(val myProject: Project, private val prop: String, priva
 
         val result = try {
             ToolchainFunctionProvider.lookup("DatabaseFunctionProvider")
-                ?.execute(myProject, prop, args, emptyMap())
+                ?.execute(myProject, prop, args, emptyMap(), "")
         } catch (e: Exception) {
             AutoDevNotifications.notify(myProject, "Error: ${e.message}")
             return "Error: ${e.message}"

exts/ext-database/src/main/kotlin/cc/unitmesh/database/provider/DatabaseFunctionProvider.kt

@@ -10,6 +10,7 @@ import com.intellij.database.model.DasTable
 import com.intellij.database.model.RawDataSource
 import com.intellij.openapi.diagnostic.logger
 import com.intellij.openapi.project.Project
+import com.intellij.openapi.util.NlsSafe
 
 class DatabaseFunctionProvider : ToolchainFunctionProvider {
     override fun toolInfos(): List<AgentTool> {
@@ -26,6 +27,7 @@ class DatabaseFunctionProvider : ToolchainFunctionProvider {
         prop: String,
         args: List<Any>,
         allVariables: Map<String, Any?>,
+        commandName: @NlsSafe String,
     ): Any {
         val databaseFunction = DatabaseFunction.fromString(prop)
             ?: throw IllegalArgumentException("[Database]: Invalid Database function name")

exts/ext-dependencies/src/233/main/kotlin/cc/unitmesh/dependencies/DependenciesFunctionProvider.kt

@@ -9,6 +9,7 @@ import com.intellij.openapi.progress.ProgressManager
 import com.intellij.openapi.progress.Task
 import com.intellij.openapi.progress.impl.BackgroundableProcessIndicator
 import com.intellij.openapi.project.Project
+import com.intellij.openapi.util.NlsSafe
 import com.intellij.packageChecker.model.ProjectDependenciesModel
 import org.jetbrains.security.`package`.Package
 import java.util.concurrent.CompletableFuture
@@ -22,7 +23,8 @@ class DependenciesFunctionProvider : ToolchainFunctionProvider {
         project: Project,
         prop: String,
         args: List<Any>,
-        allVariables: Map<String, Any?>
+        allVariables: Map<String, Any?>,
+        commandName: @NlsSafe String
     ): Any {
         val modules = ModuleManager.getInstance(project).modules
         val future = CompletableFuture<String>()

exts/ext-endpoints/src/233/main/kotlin/cc/unitmesh/endpoints/bridge/WebApiViewFunctionProvider.kt

@@ -9,6 +9,7 @@ import com.intellij.openapi.progress.ProgressManager
 import com.intellij.openapi.progress.Task
 import com.intellij.openapi.progress.impl.BackgroundableProcessIndicator
 import com.intellij.openapi.project.Project
+import com.intellij.openapi.util.NlsSafe
 import com.intellij.spring.mvc.mapping.UrlMappingElement
 import java.util.concurrent.CompletableFuture
 
@@ -21,7 +22,8 @@ class WebApiViewFunctionProvider : ToolchainFunctionProvider {
         project: Project,
         prop: String,
         args: List<Any>,
-        allVariables: Map<String, Any?>
+        allVariables: Map<String, Any?>,
+        commandName: @NlsSafe String
     ): Any {
         val future = CompletableFuture<String>()
         val task = object : Task.Backgroundable(project, "Processing context", false) {

javascript/src/main/kotlin/cc/unitmesh/ide/javascript/bridge/StylingViewFunctionProvider.kt

@@ -6,6 +6,7 @@ import cc.unitmesh.devti.provider.toolchain.ToolchainFunctionProvider
 import com.intellij.openapi.application.runReadAction
 import com.intellij.openapi.fileTypes.ex.FileTypeManagerEx
 import com.intellij.openapi.project.Project
+import com.intellij.openapi.util.NlsSafe
 import com.intellij.openapi.vfs.VirtualFile
 import com.intellij.psi.PsiManager
 import com.intellij.psi.css.CssFileType
@@ -22,7 +23,8 @@ class StylingViewFunctionProvider : ToolchainFunctionProvider {
         project: Project,
         prop: String,
         args: List<Any>,
-        allVariables: Map<String, Any?>
+        allVariables: Map<String, Any?>,
+        commandName: @NlsSafe String
     ): Any {
         val searchScope: GlobalSearchScope = ProjectScope.getContentScope(project)
         val scssType = FileTypeManagerEx.getInstanceEx().getFileTypeByExtension("scss")