opencode/yao
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update DESIGN.md to clarify MCP tool configuration and usage

Browse source 
- Revised the `Uses` struct documentation to reflect the new format for MCP tool references, changing from `mcp:<server-id>` to `mcp:<server>.<tool>`.
- Enhanced examples and descriptions throughout the document to illustrate the updated MCP tool usage in various search modes.
- Improved clarity on the configuration options for keyword extraction, QueryDSL generation, and reranking, ensuring consistency with the new MCP format.
- Updated error handling documentation to address the new MCP tool parsing logic, enhancing developer understanding of potential issues.
This commit is contained in:
Max 2025-12-12 19:20:33 +08:00
parent 73e48ce6d6
commit 26d2f7f7ed
1 changed files with 53 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

94
agent/search/DESIGN.md
View file

@ -246,10 +246,10 @@ type Searcher struct {
// Uses contains the uses.* configuration for search // Uses contains the uses.* configuration for search
type Uses struct { type Uses struct {
Web string // "builtin", "<assistant-id>", "mcp:<server-id>" Web string // "builtin", "<assistant-id>", "mcp:<server>.<tool>"
Keyword string // "builtin", "<assistant-id>", "mcp:<server-id>" Keyword string // "builtin", "<assistant-id>", "mcp:<server>.<tool>"
QueryDSL string // "builtin", "<assistant-id>", "mcp:<server-id>" QueryDSL string // "builtin", "<assistant-id>", "mcp:<server>.<tool>"
Rerank string // "builtin", "<assistant-id>", "mcp:<server-id>" Rerank string // "builtin", "<assistant-id>", "mcp:<server>.<tool>"
} }
// New creates a new Searcher instance // New creates a new Searcher instance
@ -750,7 +750,7 @@ Reranker type is determined by `uses.rerank` in `agent/agent.yml`:
- `"builtin"` - Simple score-based sorting - `"builtin"` - Simple score-based sorting
- `"<assistant-id>"` - Delegate to an assistant (Agent) - `"<assistant-id>"` - Delegate to an assistant (Agent)
- `"mcp:<server-id>"` - Call MCP server tool - `"mcp:<server>.<tool>"` - Call MCP tool (e.g., `"mcp:my-server.rerank"`)
## Citation System ## Citation System
@ -1098,25 +1098,25 @@ uses:
fetch: "workers.system.fetch" fetch: "workers.system.fetch"
# Search processing tools (NLP) # Search processing tools (NLP)
keyword: "builtin" # "builtin", "workers.nlp.keyword", "mcp:nlp-server" keyword: "builtin" # "builtin", "workers.nlp.keyword", "mcp:my-server.extract_keywords"
querydsl: "builtin" # "builtin", "workers.nlp.querydsl", "mcp:querydsl-server" querydsl: "builtin" # "builtin", "workers.nlp.querydsl", "mcp:my-server.generate_dsl"
rerank: "builtin" # "builtin", "workers.rerank", "mcp:rerank-server" rerank: "builtin" # "builtin", "workers.rerank", "mcp:my-server.rerank"
# Search handlers # Search handlers
web: "builtin" # "builtin", "workers.search.web", "mcp:search-server" web: "builtin" # "builtin", "workers.search.web", "mcp:my-server.web_search"
# Note: kb & db always use builtin (access internal data) # Note: kb & db always use builtin (access internal data)
# Note: embedding & entity follow KB collection config # Note: embedding & entity follow KB collection config
``` ```
Tool format: `"builtin"`, `"<assistant-id>"` (Agent), `"mcp:<server-id>"` (MCP) Tool format: `"builtin"`, `"<assistant-id>"` (Agent), `"mcp:<server>.<tool>"` (MCP Tool)
**Web Search Modes:** **Web Search Modes:**
| Mode | Example | Description | | Mode | Example | Description |
| --------- | ---------------------- | -------------------------------------------------------------------------- | | --------- | ---------------------------- | -------------------------------------------------------------------------- |
| `builtin` | `"builtin"` | Use built-in providers (Tavily, Serper) | | `builtin` | `"builtin"` | Use built-in providers (Tavily, Serper) |
| Agent | `"workers.search.web"` | AI-powered search: understand intent → optimize query → search → summarize | | Agent | `"workers.search.web"` | AI-powered search: understand intent → optimize query → search → summarize |
| MCP | `"mcp:search-server"` | External search service via MCP protocol | | MCP | `"mcp:my-server.web_search"` | External search tool via MCP protocol |
**Why Agent for Web Search (AI Search)?** **Why Agent for Web Search (AI Search)?**
@ -1303,7 +1303,7 @@ func (ast *Assistant) GetMergedSearchConfig() *searchTypes.Config {
{ {
// Web search settings // Web search settings
"web": { "web": {
"provider": "tavily", // "tavily", "serper", "mcp:server-id" "provider": "tavily", // "tavily", "serper" (builtin providers only)
"api_key_env": "TAVILY_API_KEY", "api_key_env": "TAVILY_API_KEY",
"max_results": 10 "max_results": 10
}, },
@ -1368,7 +1368,7 @@ func (ast *Assistant) GetMergedSearchConfig() *searchTypes.Config {
"uses": { "uses": {
"keyword": "workers.nlp.keyword", // Use LLM for keyword extraction "keyword": "workers.nlp.keyword", // Use LLM for keyword extraction
"querydsl": "workers.nlp.querydsl", // Use LLM for QueryDSL generation "querydsl": "workers.nlp.querydsl", // Use LLM for QueryDSL generation
"rerank": "mcp:rerank-server" // Use MCP for reranking "rerank": "mcp:my-server.rerank" // Use MCP tool for reranking
}, },
// Search configuration (overrides agent/search.yao) // Search configuration (overrides agent/search.yao)
@ -1534,11 +1534,11 @@ Request → Trace Start → Query Process → Search → Rerank → Citations
Configure via `uses.*` in `agent/agent.yml`: Configure via `uses.*` in `agent/agent.yml`:
| Format | Description | Use Case | | Format | Description | Use Case |
| ----------------- | ----------------------------------------- | ------------------------------ | | --------------------- | ----------------------------------------- | ------------------------------ |
| `builtin` | Rule-based, template-driven (no LLM call) | Fast, low cost, simple queries | | `builtin` | Rule-based, template-driven (no LLM call) | Fast, low cost, simple queries |
| `<assistant-id>` | Delegate to an assistant (Agent) | LLM-based, custom logic | | `<assistant-id>` | Delegate to an assistant (Agent) | LLM-based, custom logic |
| `mcp:<server-id>` | Call MCP server tool | External services integration | | `mcp:<server>.<tool>` | Call MCP tool | External services integration |
#### Keyword Extraction (`nlp/keyword.go`) #### Keyword Extraction (`nlp/keyword.go`)
@ -1557,7 +1557,7 @@ import (
// KeywordExtractor extracts keywords from user query // KeywordExtractor extracts keywords from user query
type KeywordExtractor struct { type KeywordExtractor struct {
usesKeyword string // "builtin", "<assistant-id>", "mcp:<server-id>" usesKeyword string // "builtin", "<assistant-id>", "mcp:<server>.<tool>"
config *types.KeywordConfig config *types.KeywordConfig
} }
@ -1625,7 +1625,7 @@ import (
// QueryDSLGenerator generates QueryDSL from natural language // QueryDSLGenerator generates QueryDSL from natural language
type QueryDSLGenerator struct { type QueryDSLGenerator struct {
usesQueryDSL string // "builtin", "<assistant-id>", "mcp:<server-id>" usesQueryDSL string // "builtin", "<assistant-id>", "mcp:<server>.<tool>"
config *types.QueryDSLConfig config *types.QueryDSLConfig
} }
@ -1662,11 +1662,11 @@ All handler implementations are in `search/handlers/` directory.
Web search supports three modes via `uses.web`: Web search supports three modes via `uses.web`:
| Mode | Value | Description | | Mode | Value | Description |
| ------- | ---------------------- | ------------------------------------------- | | ------- | ---------------------------- | ------------------------------------------- |
| Builtin | `"builtin"` | Direct API calls to Tavily/Serper | | Builtin | `"builtin"` | Direct API calls to Tavily/Serper |
| Agent | `"workers.search.web"` | AI-powered search with intent understanding | | Agent | `"workers.search.web"` | AI-powered search with intent understanding |
| MCP | `"mcp:search-server"` | External search service | | MCP | `"mcp:my-server.web_search"` | External search tool via MCP |
```go ```go
// handlers/web/handler.go // handlers/web/handler.go
@ -1681,7 +1681,7 @@ import (
// Handler implements web search // Handler implements web search
type Handler struct { type Handler struct {
usesWeb string // "builtin", "<assistant-id>", "mcp:<server-id>" usesWeb string // "builtin", "<assistant-id>", "mcp:<server>.<tool>"
config *types.WebConfig config *types.WebConfig
} }
@ -1724,10 +1724,16 @@ func (h *Handler) agentSearch(ctx *context.Context, req *types.Request) (*types.
return nil, nil return nil, nil
} }
// mcpSearch calls external MCP server // mcpSearch calls external MCP tool
func (h *Handler) mcpSearch(ctx *context.Context, req *types.Request) (*types.Result, error) { func (h *Handler) mcpSearch(ctx *context.Context, req *types.Request) (*types.Result, error) {
serverID := strings.TrimPrefix(h.usesWeb, "mcp:") // Parse "mcp:server.tool"
// Call MCP server's search tool mcpRef := strings.TrimPrefix(h.usesWeb, "mcp:")
parts := strings.SplitN(mcpRef, ".", 2)
if len(parts) != 2 {
return nil, fmt.Errorf("invalid MCP format, expected 'mcp:server.tool', got '%s'", h.usesWeb)
}
serverID, toolName := parts[0], parts[1]
// Call MCP tool
return nil, nil return nil, nil
} }
``` ```
@ -1903,8 +1909,14 @@ func NewReranker(usesRerank string) interfaces.Reranker {
case usesRerank == "builtin" || usesRerank == "": case usesRerank == "builtin" || usesRerank == "":
return NewBuiltinReranker() return NewBuiltinReranker()
case strings.HasPrefix(usesRerank, "mcp:"): case strings.HasPrefix(usesRerank, "mcp:"):
serverID := strings.TrimPrefix(usesRerank, "mcp:") // Parse "mcp:server.tool"
return NewMCPReranker(serverID) mcpRef := strings.TrimPrefix(usesRerank, "mcp:")
parts := strings.SplitN(mcpRef, ".", 2)
if len(parts) != 2 {
// Invalid format, fallback to builtin
return NewBuiltinReranker()
}
return NewMCPReranker(parts[0], parts[1]) // serverID, toolName
default: default:
// Assume it's an assistant ID // Assume it's an assistant ID
return NewAgentReranker(usesRerank) return NewAgentReranker(usesRerank)
@ -1917,15 +1929,15 @@ func NewReranker(usesRerank string) interfaces.Reranker {
| `rerank.go` | Factory and common logic | | `rerank.go` | Factory and common logic |
| `builtin.go` | Simple score sorting (default) | | `builtin.go` | Simple score sorting (default) |
| `agent.go` | Delegate to an assistant (Agent) | | `agent.go` | Delegate to an assistant (Agent) |
| `mcp.go` | Call MCP server rerank tool | | `mcp.go` | Call MCP tool for reranking |
Configure via `uses.rerank` in `agent/agent.yml`: Configure via `uses.rerank` in `agent/agent.yml`:
| Value | Notes | | Value | Notes |
| ------------------- | -------------------------------- | | ---------------------- | -------------------------------- |
| `builtin` | Simple score sorting (default) | | `builtin` | Simple score sorting (default) |
| `workers.rerank` | Delegate to an assistant (Agent) | | `workers.rerank` | Delegate to an assistant (Agent) |
| `mcp:rerank-server` | Call MCP server rerank tool | | `mcp:my-server.rerank` | Call MCP tool for reranking |
## Error Handling ## Error Handling