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.

At the beginning of an infrastructure-related task, agents should call get_agent_usage_guide() if they are not already familiar with this workflow.

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.

The default stance is: if the agent learns a durable, non-secret infrastructure fact that will be useful later, the agent should update Gnexus Book during the same task.

Durable facts include:

• a new or changed host, VM, VPS, router, device, or physical server;
• a new or changed IP address, hostname, MAC address, domain, port, route, upstream, VPN path, or network segment;
• a new or changed service, project, repository, deployment path, owner, version, status, or dependency;
• a live observation that contradicts existing documentation;
• a user-provided clarification that changes the meaning of existing docs;
• evidence that a project is active, dormant, abandoned, deployed, or no longer deployed.

Do not update the canonical docs for purely temporary observations unless they are useful as discovery notes. Use 90-maintenance/discovery-observations/ for scans, uncertain findings, or facts that should not yet become canonical inventory.

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.

If the agent decides not to update Gnexus Book after learning a relevant fact, it should state why. Acceptable reasons include:

• the fact is sensitive and would expose a secret;
• the fact is too temporary or uncertain;
• the user explicitly asked not to document it;
• the change requires a larger documentation pass and should be queued.

Tool Selection

Use this decision table:

End-Of-Task Checklist

Before finishing an infrastructure-related task, the agent should check:

• Did I learn a durable infrastructure fact?
• Did I discover a mismatch between live state and documentation?
• Did I add or update documentation/inventory?
• If not, did I explain why not?
• Did I run validation after changes?
• Did I create a local Git commit when changes were applied?

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.