feat: Page AI Reasonix desktop session alignment, settings IA cleanup, knowledge RAG hardening

- ACP client/session manager: Reasonix desktop live session context - Hermes tools: knowledge_rag tool manifest and skill updates - Browser runtime: sidebar page AI permission/profile/render/session/tree modules - Routes: hermes_client, hermes_tools, knowledge_rag, web_shell - Scripts: reasonix ACP wrapper, LightRAG MCP, smoke tasks 159/558/559/561/562 - Skills: mnote-knowledge-rag and mnote-lightrag-bridge SKILL.md updates
2026-06-13 22:20:01 +08:00
parent 2236a053c0
commit 4a7efd4a30
30 changed files with 5321 additions and 291 deletions
@@ -13,6 +13,7 @@ from typing import Any

 import httpx
 from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations


 DEFAULT_ENV_FILE = "/mnt/Data1T/Mnote_data/lightrag/LightRAG/.env"
@@ -21,6 +22,7 @@ DEFAULT_ROOT_URI = "file:///mnt/Data1T/Mnote_data/users/mnote-e2e/workspaces/my-
 DEFAULT_WORKSPACE_ID = "local-ws:mnote-e2e:my-space"

 mcp = FastMCP("MNote-LightRAG-Server")
+READ_ONLY_TOOL = ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False)


 def _read_env_value(key: str, env_file: str) -> str:
@@ -43,6 +45,8 @@ def _lightrag_base_url() -> str:
    env_file = os.environ.get("MNOTE_LIGHTRAG_ENV_FILE", DEFAULT_ENV_FILE)
    host = os.environ.get("LIGHTRAG_HOST") or _read_env_value("HOST", env_file) or "127.0.0.1"
    port = os.environ.get("LIGHTRAG_PORT") or _read_env_value("PORT", env_file) or "9621"
+    if host in {"0.0.0.0", "::"}:
+        host = "127.0.0.1"
    return f"http://{host}:{port}".rstrip("/")


@@ -85,9 +89,48 @@ async def _request_lightrag(path: str, *, method: str = "GET", json_body: Any =
    return {"status": "success", "response": payload, "error": None, "httpStatus": response.status_code}


+async def _request_mnote(path: str, *, method: str = "GET", json_body: Any = None, params: dict[str, Any] | None = None) -> Any:
+    headers = _mnote_headers()
+    if method.upper() == "GET":
+        headers = {key: value for key, value in headers.items() if key != "content-type"}
+    async with httpx.AsyncClient(timeout=180) as client:
+        response = await client.request(
+            method,
+            f"{_mnote_web_url()}{path}",
+            headers=headers,
+            json=json_body,
+            params=params,
+        )
+    try:
+        payload = response.json()
+    except Exception:
+        payload = {"text": response.text}
+    if response.status_code >= 400:
+        return {"status": "error", "response": None, "error": payload, "httpStatus": response.status_code}
+    return {"status": "success", "response": payload, "error": None, "httpStatus": response.status_code}
+
+
+@mcp.tool(
+    name="connect",
+    description="No-op connection probe for agents that expect MCP servers to expose a connect tool.",
+    annotations=READ_ONLY_TOOL,
+)
+async def connect() -> Any:
+    return {
+        "status": "success",
+        "response": {
+            "server": "mnote_lightrag_bridge",
+            "connected": True,
+        },
+        "error": None,
+        "httpStatus": 200,
+    }
+
+
@mcp.tool(
    name="verify_server_health",
    description="Check whether the configured local LightRAG server is healthy.",
+    annotations=READ_ONLY_TOOL,
 )
 async def verify_server_health() -> Any:
    return await _request_lightrag("/health")
@@ -96,6 +139,7 @@ async def verify_server_health() -> Any:
@mcp.tool(
    name="check_indexing_status",
    description="Check the LightRAG document processing pipeline status.",
+    annotations=READ_ONLY_TOOL,
 )
 async def check_indexing_status() -> Any:
    return await _request_lightrag("/documents/pipeline_status")
@@ -104,6 +148,7 @@ async def check_indexing_status() -> Any:
@mcp.tool(
    name="list_all_docs",
    description="List documents currently known to LightRAG.",
+    annotations=READ_ONLY_TOOL,
 )
 async def list_all_docs() -> Any:
    return await _request_lightrag("/documents")
@@ -111,39 +156,135 @@ async def list_all_docs() -> Any:

@mcp.tool(
    name="query_knowledge_graph",
-    description="Search the local LightRAG knowledge base. Use mix by default; references include provider file_path/chunk_id for MNote citation mapping.",
+    description="Ask MNote knowledge_rag.query. This calls MNote's LightRAG facade so references/citations are already mapped to MNote source registry and clickable locators.",
+    annotations=READ_ONLY_TOOL,
 )
 async def query_knowledge_graph(
    prompt: str,
    search_mode: str = "mix",
    limit: int = 60,
-    context_only: bool = False,
-    prompt_only: bool = False,
-    include_references: bool = True,
    include_chunk_content: bool = True,
+    include_document_structure_index: bool = False,
+    source_paths: list[str] | None = None,
+    workspace_id: str = DEFAULT_WORKSPACE_ID,
+    root_uri: str = DEFAULT_ROOT_URI,
+) -> Any:
+    return await mnote_knowledge_rag_query(
+        query=prompt,
+        mode=search_mode,
+        top_k=limit,
+        chunk_top_k=limit,
+        include_chunk_content=include_chunk_content,
+        include_document_structure_index=include_document_structure_index,
+        source_paths=source_paths,
+        workspace_id=workspace_id,
+        root_uri=root_uri,
+    )
+
+
+@mcp.tool(
+    name="mnote_knowledge_rag_status",
+    description="Call MNote mnote.knowledge_rag.status for provider health, source registry and sync state.",
+    annotations=READ_ONLY_TOOL,
+)
+async def mnote_knowledge_rag_status(
+    workspace_id: str = DEFAULT_WORKSPACE_ID,
+    root_uri: str = DEFAULT_ROOT_URI,
+) -> Any:
+    return await _request_mnote(
+        "/api/knowledge-rag/status",
+        method="GET",
+        params={"workspaceId": workspace_id, "rootUri": root_uri},
+    )
+
+
+@mcp.tool(
+    name="mnote_knowledge_rag_query",
+    description="Call MNote mnote.knowledge_rag.query. Use this for knowledge-library answers that need references/citations/clickable MNote locators. For book-like files pass source_paths and include_document_structure_index=true.",
+    annotations=READ_ONLY_TOOL,
+)
+async def mnote_knowledge_rag_query(
+    query: str,
+    mode: str = "mix",
+    top_k: int = 40,
+    chunk_top_k: int = 20,
+    include_chunk_content: bool = True,
+    include_document_structure_index: bool = False,
+    source_paths: list[str] | None = None,
+    workspace_id: str = DEFAULT_WORKSPACE_ID,
+    root_uri: str = DEFAULT_ROOT_URI,
 ) -> Any:
    mode_aliases = {
        "keyword": "naive",
        "semantic": "hybrid",
    }
-    mode = mode_aliases.get(search_mode, search_mode)
+    resolved_mode = mode_aliases.get(mode, mode)
    body = {
-        "query": prompt,
-        "mode": mode,
-        "top_k": limit,
-        "chunk_top_k": limit,
-        "only_need_context": context_only,
-        "only_need_prompt": prompt_only,
-        "include_references": include_references,
-        "include_chunk_content": include_chunk_content,
-        "response_type": "Multiple Paragraphs",
+        "workspaceId": workspace_id,
+        "rootUri": root_uri,
+        "query": query,
+        "mode": resolved_mode,
+        "topK": top_k,
+        "chunkTopK": chunk_top_k,
+        "includeChunkContent": include_chunk_content,
+        "includeDocumentStructureIndex": include_document_structure_index,
    }
-    return await _request_lightrag("/query", method="POST", json_body=body)
+    if source_paths:
+        body["sourcePaths"] = source_paths
+    return await _request_mnote("/api/knowledge-rag/query", method="POST", json_body=body)
+
+
+@mcp.tool(
+    name="mnote_knowledge_rag_section_context",
+    description="Call MNote mnote.knowledge_rag.section_context. Use documentStructureIndex section ranges to fetch bounded LightRAG sidecar blocks/chunks for second-pass reading of book-like/long documents.",
+    annotations=READ_ONLY_TOOL,
+)
+async def mnote_knowledge_rag_section_context(
+    source_path: str = "",
+    source_id: str = "",
+    light_rag_doc_id: str = "",
+    file_path: str = "",
+    section_id: str = "",
+    start_block_ordinal: int | None = None,
+    end_block_ordinal: int | None = None,
+    start_paragraph_ordinal: int | None = None,
+    end_paragraph_ordinal: int | None = None,
+    context_before: int = 1,
+    context_after: int = 1,
+    max_blocks: int = 24,
+    max_chars: int = 12000,
+    workspace_id: str = DEFAULT_WORKSPACE_ID,
+    root_uri: str = DEFAULT_ROOT_URI,
+) -> Any:
+    body: dict[str, Any] = {
+        "workspaceId": workspace_id,
+        "rootUri": root_uri,
+        "contextBefore": context_before,
+        "contextAfter": context_after,
+        "maxBlocks": max_blocks,
+        "maxChars": max_chars,
+    }
+    optional_values = {
+        "sourcePath": source_path,
+        "sourceId": source_id,
+        "lightRagDocId": light_rag_doc_id,
+        "filePath": file_path,
+        "sectionId": section_id,
+        "startBlockOrdinal": start_block_ordinal,
+        "endBlockOrdinal": end_block_ordinal,
+        "startParagraphOrdinal": start_paragraph_ordinal,
+        "endParagraphOrdinal": end_paragraph_ordinal,
+    }
+    for key, value in optional_values.items():
+        if value is not None and value != "":
+            body[key] = value
+    return await _request_mnote("/api/knowledge-rag/section-context", method="POST", json_body=body)


@mcp.tool(
    name="open_mnote_reference",
    description="Map a LightRAG reference/file_path/chunk_id to an MNote clickable citationUrl using MNote source registry.",
+    annotations=READ_ONLY_TOOL,
 )
 async def open_mnote_reference(
    file_path: str,
@@ -162,21 +303,36 @@ async def open_mnote_reference(
        body["chunkId"] = chunk_id
    if reference_id:
        body["referenceId"] = reference_id
-    async with httpx.AsyncClient(timeout=60) as client:
-        response = await client.post(
-            f"{_mnote_web_url()}/api/knowledge-rag/open-reference",
-            headers=_mnote_headers(),
-            json=body,
-        )
-    try:
-        payload = response.json()
-    except Exception:
-        payload = {"text": response.text}
-    if response.status_code >= 400:
-        return {"status": "error", "response": None, "error": payload, "httpStatus": response.status_code}
+    result = await _request_mnote("/api/knowledge-rag/open-reference", method="POST", json_body=body)
+    payload = result.get("response")
+    if result.get("status") != "success":
+        return result
    if not include_registry and isinstance(payload, dict):
        payload = {key: value for key, value in payload.items() if key != "registry"}
-    return {"status": "success", "response": payload, "error": None, "httpStatus": response.status_code}
+    return {"status": "success", "response": payload, "error": None, "httpStatus": result.get("httpStatus")}
+
+
+@mcp.tool(
+    name="mnote_knowledge_rag_open_reference",
+    description="Call MNote mnote.knowledge_rag.open_reference to convert a returned reference/file_path/chunk_id into a clickable MNote locator.",
+    annotations=READ_ONLY_TOOL,
+)
+async def mnote_knowledge_rag_open_reference(
+    file_path: str,
+    chunk_id: str = "",
+    reference_id: str = "",
+    workspace_id: str = DEFAULT_WORKSPACE_ID,
+    root_uri: str = DEFAULT_ROOT_URI,
+    include_registry: bool = False,
+) -> Any:
+    return await open_mnote_reference(
+        file_path=file_path,
+        chunk_id=chunk_id,
+        reference_id=reference_id,
+        workspace_id=workspace_id,
+        root_uri=root_uri,
+        include_registry=include_registry,
+    )


 if __name__ == "__main__":