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:
@@ -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)
|
||||
|
||||
|
||||
@@ -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: {},
|
||||
|
||||
@@ -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(
|
||||
[
|
||||
|
||||
Reference in New Issue
Block a user