feat(mcp): add agent-friendly query capabilities

Add get_mcp_capabilities so remote agents can discover enabled tool groups and preferred entrypoints.

Add ask_wiki as a one-call query wrapper with structured result fields while keeping the legacy answer field for compatibility.

Update MCP startup guidance and docs, and cover the new query/capability behavior with tests.
This commit is contained in:
Codex
2026-07-08 16:53:59 +00:00
parent 1150107aa3
commit ee7defe8bf
8 changed files with 368 additions and 15 deletions
+68
View File
@@ -150,8 +150,76 @@ class McpQueryTests(unittest.TestCase):
self.assertEqual(result["state"], "succeeded")
self.assertIn("Based on the wiki", result["answer"])
self.assertEqual(result["answer_markdown"], result["answer"])
self.assertEqual(result["citations"], [])
self.assertFalse(result["used_business_facts"])
self.assertTrue(result["used_wiki"])
self.assertEqual(result["data_freshness"], [])
self.assertEqual(result["confidence"], "high")
self.assertEqual(result["warnings"], [])
self.assertIn("Answer body", result["opencode_output_tail"])
def test_query_result_extracts_structured_metadata_from_output(self):
popen = FakePopen(returncode=None)
with (
patch("obsidian_wiki.mcp_query.subprocess.run", side_effect=self._fake_static_readiness_run),
patch("obsidian_wiki.mcp_query.subprocess.Popen", return_value=popen),
):
job = self.manager.start_query_job("customer situation?")
log_path = Path(self.manager._load_job(job["job_id"])["log_path"])
log_path.write_text(
"Based on [[Mini FAKRA]] and [[BJD]].\n"
"Business facts used. Data through 2026-06-02.\n"
"Answer body\n",
encoding="utf-8",
)
popen.returncode = 0
result = self.manager.get_query_job_result(job["job_id"])
self.assertEqual(result["answer_markdown"], result["answer"])
self.assertEqual(result["citations"], ["Mini FAKRA", "BJD"])
self.assertTrue(result["used_business_facts"])
self.assertTrue(result["used_wiki"])
self.assertEqual(result["data_freshness"], ["2026-06-02"])
self.assertEqual(result["confidence"], "high")
def test_query_result_marks_failed_jobs_low_confidence_with_warnings(self):
popen = FakePopen(returncode=1)
with (
patch("obsidian_wiki.mcp_query.subprocess.run", side_effect=self._fake_static_readiness_run),
patch("obsidian_wiki.mcp_query.subprocess.Popen", return_value=popen),
):
job = self.manager.start_query_job("what failed?")
log_path = Path(self.manager._load_job(job["job_id"])["log_path"])
log_path.write_text("Traceback: failed\n", encoding="utf-8")
result = self.manager.get_query_job_result(job["job_id"])
self.assertEqual(result["state"], "failed")
self.assertEqual(result["confidence"], "low")
self.assertTrue(any("failed" in warning.lower() for warning in result["warnings"]))
def test_ask_wiki_returns_timeout_payload_with_job_id(self):
popen = FakePopen(returncode=None)
with (
patch("obsidian_wiki.mcp_query.subprocess.run", side_effect=self._fake_static_readiness_run),
patch("obsidian_wiki.mcp_query.subprocess.Popen", return_value=popen),
):
result = self.manager.ask_wiki(
"slow question?",
timeout_seconds=0,
poll_interval_seconds=1,
)
self.assertEqual(result["state"], "running")
self.assertRegex(result["job_id"], r"^[0-9a-f]{32}$")
self.assertEqual(result["next_poll_after_seconds"], 1)
self.assertIn("timed out", " ".join(result["warnings"]).lower())
def test_jobs_queue_one_at_a_time_and_cancel_queued_job(self):
popen = FakePopen(returncode=None)
+94
View File
@@ -416,12 +416,14 @@ class RemoteMcpServerTests(unittest.TestCase):
self.assertIn("search_file_assets", FakeMCP.tool_names)
self.assertIn("list_file_assets", FakeMCP.tool_names)
self.assertIn("get_file_asset_metadata", FakeMCP.tool_names)
self.assertIn("get_mcp_capabilities", FakeMCP.tool_names)
self.assertIn("how_to_use_wiki_file_assets", FakeMCP.prompt_names)
self.assertNotIn("create_ingest_upload", FakeMCP.tool_names)
def test_create_server_registers_ingest_tools_when_enabled(self):
class FakeMCP:
tool_names = []
tools = {}
def __init__(self, _name, **_kwargs):
pass
@@ -429,6 +431,7 @@ class RemoteMcpServerTests(unittest.TestCase):
def tool(self):
def decorator(func):
self.tool_names.append(func.__name__)
self.tools[func.__name__] = func
return func
return decorator
@@ -474,6 +477,7 @@ class RemoteMcpServerTests(unittest.TestCase):
def test_create_server_registers_query_tools_only_when_enabled(self):
class FakeMCP:
tool_names = []
tools = {}
def __init__(self, _name, **_kwargs):
pass
@@ -481,6 +485,7 @@ class RemoteMcpServerTests(unittest.TestCase):
def tool(self):
def decorator(func):
self.tool_names.append(func.__name__)
self.tools[func.__name__] = func
return func
return decorator
@@ -498,6 +503,16 @@ class RemoteMcpServerTests(unittest.TestCase):
return decorator
class FakeQueryManager:
def ask_wiki(self, query, mode="normal", public_only=False, note=None, timeout_seconds=90, poll_interval_seconds=2):
return {
"job_id": "query-job",
"state": "succeeded",
"answer": "answer",
"answer_markdown": "answer",
"citations": [],
"warnings": [],
}
def start_query_job(self, query, mode="normal", public_only=False, note=None):
return {"job_id": "query-job", "state": "queued"}
@@ -532,11 +547,89 @@ class RemoteMcpServerTests(unittest.TestCase):
self.assertIsInstance(disabled_server, FakeMCP)
self.assertIsInstance(enabled_server, FakeMCP)
self.assertNotIn("start_wiki_query", disabled_tool_names)
self.assertNotIn("ask_wiki", disabled_tool_names)
self.assertIn("ask_wiki", FakeMCP.tool_names)
self.assertIn("start_wiki_query", FakeMCP.tool_names)
self.assertIn("get_wiki_query_status", FakeMCP.tool_names)
self.assertIn("get_wiki_query_result", FakeMCP.tool_names)
self.assertIn("cancel_wiki_query", FakeMCP.tool_names)
self.assertIn("check_query_opencode_readiness", FakeMCP.tool_names)
self.assertEqual(
FakeMCP.tools["ask_wiki"]("what do I know?", timeout_seconds=3, poll_interval_seconds=1)["answer_markdown"],
"answer",
)
def test_get_mcp_capabilities_reports_agent_facing_tools_without_local_paths(self):
class FakeMCP:
tools = {}
def __init__(self, _name, **_kwargs):
pass
def tool(self):
def decorator(func):
self.tools[func.__name__] = func
return func
return decorator
def resource(self, *_args, **_kwargs):
def decorator(func):
return func
return decorator
def prompt(self, *_args, **_kwargs):
def decorator(func):
return func
return decorator
with (
tempfile.TemporaryDirectory() as tmp,
patch.dict("sys.modules", {"mcp.server.fastmcp": type("Mod", (), {"FastMCP": FakeMCP})()}),
):
root = Path(tmp)
mcp_server.create_server(
vault_path=root / "vault",
enable_ingest=True,
enable_query=True,
project_root=root / "project",
ingest_runtime_root=root / "ingest-runtime",
query_runtime_root=root / "query-runtime",
ingest_manager=IngestManager(
vault_path=root / "vault",
project_root=root / "project",
runtime_root=root / "fake-ingest",
),
query_manager=type(
"FakeQueryManager",
(),
{
"ask_wiki": lambda self, query, mode="normal", public_only=False, note=None, timeout_seconds=90, poll_interval_seconds=2: {},
"start_query_job": lambda self, query, mode="normal", public_only=False, note=None: {},
"get_query_job_status": lambda self, job_id: {},
"get_query_job_result": lambda self, job_id: {},
"cancel_query_job": lambda self, job_id: {},
"check_opencode_readiness": lambda self, run_smoke_test=False: {},
},
)(),
)
capabilities = FakeMCP.tools["get_mcp_capabilities"]()
self.assertEqual(capabilities["server_name"], "wiki-file-assets")
self.assertEqual(capabilities["enabled_tools"], ["file-assets", "ingest", "query"])
self.assertTrue(capabilities["query"]["enabled"])
self.assertEqual(capabilities["query"]["preferred_tool"], "ask_wiki")
self.assertIn("ask_wiki", capabilities["query"]["tools"])
self.assertTrue(capabilities["ingest"]["enabled"])
self.assertEqual(capabilities["ingest"]["http_upload_path"], "/mcp-ingest/uploads")
self.assertEqual(capabilities["ingest"]["preferred_text_tool"], "ingest_text_note")
self.assertIn("search_file_assets", capabilities["file_assets"]["tools"])
self.assertNotIn("vault_path", json.dumps(capabilities))
self.assertNotIn("runtime", json.dumps(capabilities).lower())
self.assertNotIn("Bearer ", json.dumps(capabilities))
self.assertNotIn("upload_token", json.dumps(capabilities))
def test_file_index_status_reports_opencode_model_settings(self):
class FakeMCP:
@@ -589,6 +682,7 @@ class RemoteMcpServerTests(unittest.TestCase):
"FakeQueryManager",
(),
{
"ask_wiki": lambda self, query, mode="normal", public_only=False, note=None, timeout_seconds=90, poll_interval_seconds=2: {},
"start_query_job": lambda self, query, mode="normal", public_only=False, note=None: {},
"get_query_job_status": lambda self, job_id: {},
"get_query_job_result": lambda self, job_id: {},
+1
View File
@@ -332,6 +332,7 @@ class McpServiceConfigTests(unittest.TestCase):
self.assertIn("OBSIDIAN_MCP_QUERY_OPENCODE_VARIANT=minimal\n", env_content)
self.assertNotIn("OBSIDIAN_MCP_INGEST_OPENCODE_PATH=", env_content)
self.assertIn("Enabled tool groups:\nfile-assets,query", output)
self.assertIn("Use ask_wiki for ordinary wiki, business facts, or hybrid questions.", output)
prepare_runtime.assert_called_once_with(project_root, uv_path=Path("/home/nac/.local/bin/uv"))
run_systemctl.assert_has_calls(
[