[mmhh256]

Description

External agents using the built-in MCP search_knowledge tool can now cite the retrieved documents without invoking ask. The structured passage results retain their existing document and chunk IDs and include knowledge_filename and source_locators when the retrieval result has them. For example, a PDF hit can identify page 3 in the original file. These are citation fields, with file access still governed by existing permissions.

AI assistance: OpenAI Codex investigated, implemented, tested, and self-reviewed the changes.

Type of Change

• ✨ New feature
• 📚 Documentation update
• 🧪 Test

Related Issue

Fixes #4233

Testing

• The MCP JSON-RPC regression test fails on the unchanged implementation for hybrid, semantic, and keyword search because the file fields are absent.
• go test ./internal/mcpserver ./internal/agent/tools -count=1 passes. The regression tests verify the filename and PDF page location and check that unavailable metadata is omitted.
• golangci-lint run --new-from-rev=origin/main ./... reports zero issues.
• git diff --check origin/main...HEAD passes.
• Full-repository tests were not run locally. Tests exercise the MCP endpoint with a fixture-backed retrieval service.

Checklist

• Changed source files are formatted
• Targeted tests and diff-scoped lint pass
• Self-reviewed the code
• Added regression coverage
• Updated MCP documentation

[Copilot]

🟢 Approval recommended

No active review issues remain for the changes adding direct citation metadata to search results.

No open issues 🎉

What changed in this PR

This PR addresses #4233 by letting external MCP clients cite retrieved passages directly from search_knowledge, without invoking ask. Citation metadata does not change existing file-access permissions.

Changes:

• Adds optional knowledge_filename and source_locators fields to structured passage results while preserving document and chunk IDs.
• Adds regression assertions for metadata propagation across hybrid, semantic, and keyword search, plus omission when metadata is unavailable.
• Updates the tool description and MCP documentation to explain direct citation support.

File	Description
website-docs/​03-features/​08-mcp.md	Documents citation fields, optional availability, and usage without ask.
internal/​mcpserver/​tools_search_documents_test.go	Checks filename and PDF-page propagation, plus omission of unavailable metadata.
internal/​mcpserver/​tools_retrieve.go	Updates the search tool description to advertise source filenames and locations.
internal/​agent/​tools/​search_knowledge.go	Includes available filename and source locators in structured passage results.

_{Review effort: Balanced}