diff --git a/10-systems/applications/gnexus-book.md b/10-systems/applications/gnexus-book.md index fbd0a50..799a8cf 100644 --- a/10-systems/applications/gnexus-book.md +++ b/10-systems/applications/gnexus-book.md @@ -19,6 +19,7 @@ ## Runtime Components - Backend: FastAPI under `server/`. +- Agent interface: MCP server under `server/app/mcp_server.py`. - UI: Vue/Vite under `ui/`. - UI dependency: `gnexus-ui-kit`. @@ -33,4 +34,6 @@ Agents should prefer structured inventory changes, validation, pending changes, and local commits through the maintenance API. +For agent-facing MCP usage rules, see [../../90-maintenance/agent-mcp-usage.md](../../90-maintenance/agent-mcp-usage.md). + No raw credentials are documented here. diff --git a/90-maintenance/agent-mcp-usage.md b/90-maintenance/agent-mcp-usage.md new file mode 100644 index 0000000..0e3ae33 --- /dev/null +++ b/90-maintenance/agent-mcp-usage.md @@ -0,0 +1,124 @@ +--- +owner: gmikcon +status: active +last_reviewed: 2026-05-11 +review_interval: 30d +confidence: high +source_of_truth: repository +--- + +# Agent MCP Usage + +This document explains what the Gnexus Book MCP server is for and how an AI agent should use it. + +## Purpose + +Gnexus Book is the canonical knowledge base for the owner's digital and server infrastructure. + +The MCP server is the agent-facing interface to that knowledge base. It lets an agent read and maintain documentation without knowing the repository layout, raw REST API, or Git workflow. + +The MCP server is valuable because it gives agents: + +- stable access to canonical Markdown documentation; +- structured YAML inventory for hosts, services, domains, networks, endpoints, projects, databases, backups, hardware, and virtual machines; +- relationship graph data across inventory records; +- freshness and validation checks; +- controlled write operations through pending changes, validation, and local Git commits. + +## Proactive Usage Rule + +Agents should not wait for the user to explicitly say "look in the knowledge base". + +If a task mentions or depends on the owner's infrastructure, the agent should consult Gnexus Book proactively before giving a confident answer or making changes. + +Use MCP proactively for questions about: + +- hosts, servers, VPS, VMs, hardware, routers, or local devices; +- IP addresses, domains, ports, routes, VPNs, proxies, nginx upstreams, or network topology; +- deployed services, web applications, smart-home components, GitBucket repositories, or project ownership; +- whether something is local, VPN-only, public, stale, undocumented, or dependent on another component; +- where a project is hosted, deployed, or documented; +- what an agent should update after discovering new infrastructure facts. + +## When Not To Use It + +Do not use MCP for unrelated general knowledge. + +Do not use MCP to store secrets. Raw passwords, access tokens, private keys, recovery codes, session cookies, and secret config values must not be written to documentation or pending changes. + +It is acceptable to document non-secret operational identifiers: + +- hostnames; +- usernames; +- internal and public IP addresses; +- domains; +- ports; +- credential references such as `owner-managed` or `ssh-key`; +- access model notes such as `auth required` or `read-only SSH key`. + +## Read Workflow + +Start broad, then narrow. + +1. Use `search_docs(query)` for natural-language lookup. +2. Use `read_doc(path)` for canonical narrative context. +3. Use `list_inventory(inventory_type)` for structured records. +4. Use `get_inventory_item(inventory_type, item_id)` when the id is known. +5. Use `get_relationships()` when dependencies, routes, upstreams, domains, or unresolved references matter. +6. Use `check_freshness()` when deciding whether documentation may be stale. +7. Use `validate_repository()` before trusting the repository state for maintenance work. + +Examples: + +- For `git.gnexus.space`, search docs for `git.gnexus.space`, then inspect `domains`, `services`, `endpoints`, and relationships. +- For `smart-home-server`, read the server and automation docs, then inspect `hosts`, `hardware`, `services`, `databases`, and `backups`. +- For a repository question, read the GitBucket catalog first and pay attention to last commit dates. + +## Write Workflow + +Documentation writes should be factual, focused, and committed. + +For non-trivial changes: + +1. Use `propose_doc_change` or `propose_inventory_item_change`. +2. Use `apply_pending_change`. +3. Use `validate_repository`. +4. Use `commit_changes`. + +For simple full-document changes, `update_doc` can create the pending change, apply it, validate it, and commit it in one operation. + +Every write should include: + +- a short `summary`; +- a clear `reason`; +- no raw secrets; +- `last_reviewed` updates only when the agent actually verified the fact. + +## Interpreting Repository Activity + +For GitBucket repositories, last commit date matters. + +Default interpretation: + +- repositories touched in 2026 are potentially active; +- repositories last touched in 2025 are dormant unless deployment evidence says otherwise; +- repositories last touched in 2024 are old/archive candidates until confirmed. + +Do not call a repository active only because it exists in GitBucket. + +## Conflict Handling + +If live observations and documentation disagree: + +- say what conflicts; +- prefer live observations for immediate operational decisions; +- update Gnexus Book with the new fact if it is relevant and safe to document; +- keep uncertainty explicit with `confidence`, notes, or discovery-observation docs. + +## Agent Prompt Guidance + +When this MCP server is listed in an agent's available tools, the agent should treat it as infrastructure memory. + +A good system prompt rule is: + +> Before answering infrastructure-specific questions or making infrastructure-related changes, consult Gnexus Book MCP proactively. Use it to verify documented facts, discover relationships, and update documentation after new facts are found. diff --git a/server/README.md b/server/README.md index 8b7aae2..9899e25 100644 --- a/server/README.md +++ b/server/README.md @@ -18,6 +18,8 @@ The MCP server exposes the same repository, inventory, validation, pending-change, and Git commit logic through MCP tools and resources. +It should be treated by AI agents as infrastructure memory. Agents should consult it proactively for infrastructure-specific work rather than waiting for the user to explicitly ask them to "look in the knowledge base". + Run over stdio: ```bash @@ -48,6 +50,16 @@ - `commit_changes(summary, files, details?)` - `update_doc(path, content, summary, reason?)` +Agent usage policy: + +- Use MCP before answering questions about hosts, VPS, VMs, networks, domains, routes, services, deployments, GitBucket repositories, or smart-home infrastructure. +- Use `search_docs` first for broad lookup, then `read_doc`, inventory tools, and `get_relationships` for authoritative context. +- Use `check_freshness` when stale information matters. +- Use write tools to update documentation after discovering relevant new facts. +- Never store raw passwords, tokens, private keys, recovery codes, session cookies, or secret config values. + +Detailed rules: `../90-maintenance/agent-mcp-usage.md`. + Useful resources: - `gnexus-book://docs` diff --git a/server/app/mcp_server.py b/server/app/mcp_server.py index 1f34898..3327768 100644 --- a/server/app/mcp_server.py +++ b/server/app/mcp_server.py @@ -17,6 +17,45 @@ from .validation import validate_repository +MCP_INSTRUCTIONS = """ +Gnexus Book is the canonical knowledge base for the owner's digital, server, +network, project, smart-home, and local infrastructure. + +This MCP server is not a generic file browser. It is the preferred operational +interface for AI agents that need infrastructure context or need to maintain the +knowledge base. Use it proactively when a user request mentions, depends on, or +may be affected by documented infrastructure. + +Use Gnexus Book before answering or acting when the task involves: +- hosts, VPS, VMs, servers, routers, networks, domains, ports, traffic routes, or VPNs; +- services such as GitBucket, nginx proxies, smart-home, auth, storage, media, or project deployments; +- repository/project ownership, activity, deployment mapping, or source-of-truth questions; +- credentials/access methods, but never request or store raw secrets in documentation; +- checking whether information is stale, incomplete, already documented, or safe to change; +- updating documentation after discovering new facts. + +Typical read workflow: +1. search_docs(query) for natural-language lookup. +2. read_doc(path) for canonical narrative context. +3. list_inventory(type) or get_inventory_item(type, id) for structured facts. +4. get_relationships() when dependencies, upstreams, domains, hosts, or unresolved references matter. +5. check_freshness() and validate_repository() when making maintenance decisions. + +Typical write workflow: +1. Prefer propose_doc_change or propose_inventory_item_change for non-trivial changes. +2. Use apply_pending_change to validate and apply. +3. Use commit_changes with a short factual summary. +4. For simple full-document replacements, update_doc may create, apply, validate, and commit in one call. + +Rules: +- Do not store raw passwords, tokens, private keys, recovery codes, session cookies, or secret config values. +- IP addresses, hostnames, usernames, domains, routes, ports, and credential references may be documented when useful. +- Treat Git history as the rollback mechanism; still keep changes focused and commit summaries clear. +- If documentation conflicts with live observations, say so and update the knowledge base when appropriate. +- If the user asks about infrastructure and you have this MCP server available, do not wait for the user to say "look in the knowledge base"; consult it yourself. +""".strip() + + def _settings() -> Settings: repo_root = os.environ.get("GNEXUS_BOOK_REPO_ROOT") return Settings() if not repo_root else Settings(repo_root=Path(repo_root)) @@ -152,11 +191,7 @@ mcp = FastMCP( "gnexus-book", - instructions=( - "Gnexus Book MCP exposes infrastructure documentation, inventory, " - "validation, pending changes, and local Git commit tools. " - "Do not store raw secrets in documentation." - ), + instructions=MCP_INSTRUCTIONS, ) diff --git a/server/tests/test_mcp_server.py b/server/tests/test_mcp_server.py index 6a31bdf..c7dfd9f 100644 --- a/server/tests/test_mcp_server.py +++ b/server/tests/test_mcp_server.py @@ -23,6 +23,14 @@ assert "commit_changes" in names +def test_mcp_instructions_tell_agents_to_use_knowledge_base_proactively() -> None: + assert mcp.instructions is not None + assert "canonical knowledge base" in mcp.instructions + assert "Use it proactively" in mcp.instructions + assert "do not wait for the user" in mcp.instructions + assert "Do not store raw passwords" in mcp.instructions + + def test_mcp_tool_functions_read_repository() -> None: doc = read_doc("10-systems/applications/gitbucket.md") assert doc["path"] == "10-systems/applications/gitbucket.md"