feat(cli): chunk subtree + MCP chunk_list tool + curation rationale
New subtree (chunk list / view / delete) exposes RAG retrieval debugging primitives with SDK-grounded field set (23 Chunk fields). Pagination follows v0.4 canon: --limit / --page-size (1..1000) / --all-pages. - chunk list --doc <id>: enumerate by ChunkIndex (separate from search chunks which is hybrid retrieval; Long help documents the distinction) - chunk view <id>: scope-less render via /chunks/by-id route; full content verbatim - chunk delete <id> --doc <id>: scope-flag + scope-id; L-13 destructive; 404 NOT idempotent; resource.not_found / auth.forbidden / input.confirmation_required typed exit codes documented in Long help MCP server gains chunk_list as 10th curated tool. Schema deliberately exposes only doc_id + limit (no pagination workflow on MCP); response includes truncated_at_limit flag when total > limit. cli/AGENTS.md MCP curation rationale rewritten: curated read-only is a deliberate product call because the server side does not yet enforce per-token scope. When server scope ships, mutation tools can land in the MCP surface. Shared helper cli/internal/text/timeago_string.go (FuzzyAgoStr) extracted from session list during the C2 quality-review pass.
This commit is contained in:
@@ -35,9 +35,10 @@ type ServiceClient interface {
|
||||
knowledgeService
|
||||
chatService
|
||||
agentService
|
||||
chunkListService
|
||||
}
|
||||
|
||||
// RunStdio constructs the MCP server, registers the curated 9 tools, and
|
||||
// RunStdio constructs the MCP server, registers the curated 10 tools, and
|
||||
// blocks reading JSON-RPC from stdin until the client disconnects or ctx
|
||||
// is cancelled. Returns the underlying transport error (if any); the cobra
|
||||
// RunE caller maps it through the usual cmdutil exit-code path.
|
||||
|
||||
@@ -39,6 +39,13 @@ type agentService interface {
|
||||
AgentQAStreamWithRequest(ctx context.Context, sessionID string, req *sdk.AgentQARequest, cb sdk.AgentEventCallback) error
|
||||
}
|
||||
|
||||
// chunkListService is the narrow surface chunk_list depends on. Kept
|
||||
// separate from knowledgeService because the chunk subtree is its own
|
||||
// domain on the server side (/api/v1/chunks/...).
|
||||
type chunkListService interface {
|
||||
ListKnowledgeChunks(ctx context.Context, knowledgeID string, page, pageSize int) ([]sdk.Chunk, int64, error)
|
||||
}
|
||||
|
||||
// agentInvokeService composes the two SDK methods agent_invoke needs
|
||||
// (CreateSession for the auto-session path + AgentQAStreamWithRequest
|
||||
// for the run itself). Declared here alongside the per-domain
|
||||
@@ -49,7 +56,7 @@ type agentInvokeService interface {
|
||||
AgentQAStreamWithRequest(ctx context.Context, sessionID string, req *sdk.AgentQARequest, cb sdk.AgentEventCallback) error
|
||||
}
|
||||
|
||||
// registerTools wires the curated 9 tools onto server. Adding a tool here
|
||||
// registerTools wires the curated 10 tools onto server. Adding a tool here
|
||||
// is a deliberate API expansion - the agent-callable surface is the
|
||||
// reason this CLI ships an MCP server, not its CLI command list, so this
|
||||
// list must be maintained by hand.
|
||||
@@ -63,6 +70,7 @@ func registerTools(server *mcpsdk.Server, svc ServiceClient) {
|
||||
addChat(server, svc)
|
||||
addAgentList(server, svc)
|
||||
addAgentInvoke(server, svc)
|
||||
addChunkList(server, svc)
|
||||
}
|
||||
|
||||
// ---- kb_list -------------------------------------------------------------
|
||||
@@ -445,6 +453,62 @@ func addAgentInvoke(server *mcpsdk.Server, svc agentInvokeService) {
|
||||
})
|
||||
}
|
||||
|
||||
// ---- chunk_list ----------------------------------------------------------
|
||||
|
||||
type chunkListInput struct {
|
||||
DocID string `json:"doc_id" jsonschema:"document (knowledge entry) ID"`
|
||||
Limit int `json:"limit,omitempty" jsonschema:"max chunks to return (1..1000); defaults to 50"`
|
||||
}
|
||||
|
||||
type chunkListOutput struct {
|
||||
Chunks []sdk.Chunk `json:"chunks"`
|
||||
Total int64 `json:"total"`
|
||||
TruncatedAtLimit bool `json:"truncated_at_limit"`
|
||||
}
|
||||
|
||||
// chunkListDefaultLimit + chunkListMaxLimit mirror the schema's default+max.
|
||||
// MCP schema deliberately exposes only `limit`, not the CLI's full
|
||||
// --limit/--page/--page-size triple: LLM agents typically need a single
|
||||
// bounded fetch, not pagination workflows. Above 1000, fall back to the CLI.
|
||||
const (
|
||||
chunkListDefaultLimit = 50
|
||||
chunkListMaxLimit = 1000
|
||||
)
|
||||
|
||||
func addChunkList(server *mcpsdk.Server, svc chunkListService) {
|
||||
mcpsdk.AddTool(server, &mcpsdk.Tool{
|
||||
Name: "chunk_list",
|
||||
Description: "List chunks of a knowledge document for RAG retrieval debug. Returns at most `limit` chunks starting from ChunkIndex 0; if total chunks exceed limit, truncated_at_limit=true signals the agent to fall back to the CLI for paginated retrieval.",
|
||||
}, func(ctx context.Context, _ *mcpsdk.CallToolRequest, in chunkListInput) (*mcpsdk.CallToolResult, chunkListOutput, error) {
|
||||
if in.DocID == "" {
|
||||
return nil, chunkListOutput{}, fmt.Errorf("doc_id is required")
|
||||
}
|
||||
// `limit` is typed as int by chunkListInput, so the SDK rejects
|
||||
// non-numeric values at schema validation (e.g. "limit":"50")
|
||||
// before this handler runs. Here we only default+clamp the
|
||||
// already-decoded value.
|
||||
limit := in.Limit
|
||||
if limit < 1 {
|
||||
limit = chunkListDefaultLimit
|
||||
}
|
||||
if limit > chunkListMaxLimit {
|
||||
limit = chunkListMaxLimit
|
||||
}
|
||||
chunks, total, err := svc.ListKnowledgeChunks(ctx, in.DocID, 1, limit)
|
||||
if err != nil {
|
||||
return nil, chunkListOutput{}, fmt.Errorf("list knowledge chunks: %w", err)
|
||||
}
|
||||
if chunks == nil {
|
||||
chunks = []sdk.Chunk{}
|
||||
}
|
||||
return nil, chunkListOutput{
|
||||
Chunks: chunks,
|
||||
Total: total,
|
||||
TruncatedAtLimit: total > int64(limit),
|
||||
}, nil
|
||||
})
|
||||
}
|
||||
|
||||
// encodeDownload returns (content, isBase64). Heuristic: if the first 512
|
||||
// bytes contain a NUL, treat as binary. Otherwise it's UTF-8-ish text.
|
||||
// Matches what /usr/bin/file's "binary" heuristic does at a coarse level -
|
||||
|
||||
@@ -10,6 +10,8 @@ import (
|
||||
"time"
|
||||
|
||||
mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
@@ -42,6 +44,9 @@ type fakeSvc struct {
|
||||
agentErr error
|
||||
agentEvents []*sdk.AgentStreamResponse
|
||||
agentStreamErr error
|
||||
chunks []sdk.Chunk
|
||||
chunksTotal int64
|
||||
chunksErr error
|
||||
// Captured args:
|
||||
calls struct {
|
||||
listKBs int
|
||||
@@ -59,6 +64,9 @@ type fakeSvc struct {
|
||||
agentViewID string
|
||||
agentReq *sdk.AgentQARequest
|
||||
agentSess string
|
||||
chunkDocID string
|
||||
chunkPage int
|
||||
chunkPageSize int
|
||||
}
|
||||
}
|
||||
|
||||
@@ -120,6 +128,12 @@ func (f *fakeSvc) AgentQAStreamWithRequest(_ context.Context, sess string, req *
|
||||
}
|
||||
return f.agentStreamErr
|
||||
}
|
||||
func (f *fakeSvc) ListKnowledgeChunks(_ context.Context, docID string, page, pageSize int) ([]sdk.Chunk, int64, error) {
|
||||
f.calls.chunkDocID = docID
|
||||
f.calls.chunkPage = page
|
||||
f.calls.chunkPageSize = pageSize
|
||||
return f.chunks, f.chunksTotal, f.chunksErr
|
||||
}
|
||||
|
||||
// newTestServer wires svc to an in-process MCP server and returns a
|
||||
// connected client session ready to CallTool against it.
|
||||
@@ -182,7 +196,7 @@ func TestTool_ListsRegistered(t *testing.T) {
|
||||
if err != nil {
|
||||
t.Fatalf("ListTools: %v", err)
|
||||
}
|
||||
want := []string{"kb_list", "kb_view", "doc_list", "doc_view", "doc_download", "search_chunks", "chat", "agent_list", "agent_invoke"}
|
||||
want := []string{"kb_list", "kb_view", "doc_list", "doc_view", "doc_download", "search_chunks", "chat", "agent_list", "agent_invoke", "chunk_list"}
|
||||
got := map[string]bool{}
|
||||
for _, tool := range res.Tools {
|
||||
got[tool.Name] = true
|
||||
@@ -405,3 +419,54 @@ func TestTool_AgentInvoke_StreamAbort(t *testing.T) {
|
||||
t.Fatal("expected IsError=true on mid-stream abort")
|
||||
}
|
||||
}
|
||||
|
||||
func TestTool_ChunkList_Happy(t *testing.T) {
|
||||
svc := &fakeSvc{
|
||||
chunks: []sdk.Chunk{{ID: "c1", ChunkIndex: 0, Content: "hello"}},
|
||||
chunksTotal: 1,
|
||||
}
|
||||
c, _ := newTestServer(t, svc)
|
||||
var out chunkListOutput
|
||||
callTool(t, c, "chunk_list", map[string]any{"doc_id": "doc_abc", "limit": 50}, &out)
|
||||
require.Len(t, out.Chunks, 1)
|
||||
assert.Equal(t, "c1", out.Chunks[0].ID)
|
||||
assert.Equal(t, "doc_abc", svc.calls.chunkDocID)
|
||||
assert.Equal(t, 1, svc.calls.chunkPage)
|
||||
assert.Equal(t, 50, svc.calls.chunkPageSize) // SDK page=1, pageSize=limit
|
||||
}
|
||||
|
||||
func TestTool_ChunkList_TruncatedAtLimit(t *testing.T) {
|
||||
svc := &fakeSvc{
|
||||
chunks: []sdk.Chunk{{ID: "c1"}},
|
||||
chunksTotal: 100, // more than limit
|
||||
}
|
||||
c, _ := newTestServer(t, svc)
|
||||
var out chunkListOutput
|
||||
callTool(t, c, "chunk_list", map[string]any{"doc_id": "d", "limit": 1}, &out)
|
||||
assert.True(t, out.TruncatedAtLimit)
|
||||
}
|
||||
|
||||
func TestTool_ChunkList_MissingDocID(t *testing.T) {
|
||||
c, _ := newTestServer(t, &fakeSvc{})
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
|
||||
defer cancel()
|
||||
res, err := c.CallTool(ctx, &mcpsdk.CallToolParams{Name: "chunk_list", Arguments: map[string]any{"limit": 50}})
|
||||
require.NoError(t, err)
|
||||
require.True(t, res.IsError, "expected IsError=true on missing doc_id")
|
||||
}
|
||||
|
||||
// TestTool_ChunkList_NonNumericLimit asserts the MCP framework rejects a
|
||||
// string-valued `limit`. The schema declares limit as integer (via the
|
||||
// chunkListInput struct tag), so non-numeric values fail validation
|
||||
// before the handler runs.
|
||||
func TestTool_ChunkList_NonNumericLimit(t *testing.T) {
|
||||
c, _ := newTestServer(t, &fakeSvc{})
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
|
||||
defer cancel()
|
||||
res, err := c.CallTool(ctx, &mcpsdk.CallToolParams{
|
||||
Name: "chunk_list",
|
||||
Arguments: map[string]any{"doc_id": "d", "limit": "50"},
|
||||
})
|
||||
require.NoError(t, err)
|
||||
require.True(t, res.IsError, "expected IsError=true when limit is a string")
|
||||
}
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
package text
|
||||
|
||||
import "time"
|
||||
|
||||
// FuzzyAgoStr is the string-input variant of FuzzyAgo for SDK types that
|
||||
// carry timestamps as RFC3339 strings (sdk.Chunk.UpdatedAt, sdk.Session.
|
||||
// UpdatedAt, ...) rather than time.Time.
|
||||
//
|
||||
// Behavior:
|
||||
// - ts == "" → "-" (server has no timestamp; render placeholder)
|
||||
// - parse error → ts (surface the raw value rather than hide it)
|
||||
// - parse OK → FuzzyAgo(now, parsed)
|
||||
//
|
||||
// The parse-error fallback is deliberate: if the server starts emitting a
|
||||
// new format we want it visible in the table, not silently replaced by "-".
|
||||
func FuzzyAgoStr(now time.Time, ts string) string {
|
||||
if ts == "" {
|
||||
return "-"
|
||||
}
|
||||
t, err := time.Parse(time.RFC3339, ts)
|
||||
if err != nil {
|
||||
return ts
|
||||
}
|
||||
return FuzzyAgo(now, t)
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
package text_test
|
||||
|
||||
import (
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/text"
|
||||
)
|
||||
|
||||
func TestFuzzyAgoStr(t *testing.T) {
|
||||
now := time.Date(2026, 5, 15, 12, 0, 0, 0, time.UTC)
|
||||
tests := []struct {
|
||||
name string
|
||||
ts string
|
||||
want string
|
||||
}{
|
||||
{"empty renders dash", "", "-"},
|
||||
{"valid RFC3339 5m ago", now.Add(-5 * time.Minute).Format(time.RFC3339), "about 5 minutes ago"},
|
||||
{"valid RFC3339 2d ago", now.Add(-2 * 24 * time.Hour).Format(time.RFC3339), "about 2 days ago"},
|
||||
{"unparseable returned verbatim", "not-a-date", "not-a-date"},
|
||||
{"wrong format returned verbatim", "2026-05-15 12:00:00", "2026-05-15 12:00:00"},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
got := text.FuzzyAgoStr(now, tt.ts)
|
||||
if got != tt.want {
|
||||
t.Errorf("FuzzyAgoStr(%q) = %q, want %q", tt.ts, got, tt.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user