Newer
Older
gnexus-book / server / app / mcp_server.py
from __future__ import annotations

import json
import os
from pathlib import Path
from typing import Annotated, Any, Literal

from mcp.server.fastmcp import FastMCP
from mcp.server.transport_security import TransportSecuritySettings
from pydantic import Field

from .auth.actor import Actor
from .auth.mcp_guard import mcp_actor, mcp_write_denied
from .config import Settings
from .freshness import build_freshness_report
from .git_adapter import CommitRequest, GitAdapter
from .pending_changes import ProposedChangeRequest
from .relationships import build_relationships
from .storage.db import Database
from .storage.documents import (
    diff_document_versions,
    get_document_version,
    list_document_versions,
    restore_document_version as restore_document_version_service,
)
from .storage.factory import (
    make_docs_repository,
    make_inventory_repository,
    make_pending_change_repository,
)
from .storage.freshness import build_freshness_report_db
from .storage.validation import validate_database
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(inventory_type) or get_inventory_item(inventory_type, item_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. If you learn a durable infrastructure fact that is missing, stale, or wrong, update Gnexus Book in the same task whenever practical.
2. Prefer propose_doc_change or propose_inventory_item_change for non-trivial changes.
3. Use apply_pending_change to validate and apply.
4. Use commit_changes with a short factual summary.
5. For simple full-document replacements, update_doc may create, apply, validate, and commit in one call.

Inventory creation workflow (critical):
- Some inventory schemas (e.g., hosts) require a `docs` field linking to a Markdown file.
- Before creating an inventory item with a `docs` reference, use propose_doc_change to create the target Markdown document first, then apply_pending_change to apply it.
- Only after the document exists should you propose the inventory item with the `docs` path.
- Never use local filesystem tools to edit gnexus-book repository files directly — always use the MCP tools.

Storage mode:
- In database mode, apply_pending_change publishes a changeset transactionally; commit_changes is a no-op.
- Use document_history, document_version, document_diff, and restore_document_version for version work.
- Restoring a version creates a new version; it never rewrites history.

Transport and keys:
- Production agents connect over streamable HTTP at /mcp-protocol/ with a personal mcp_* key.
- Mutating tools accept is_user; set it true only when the key owner explicitly acts as themselves.
- Tool errors are returned as data: {"error": 401|403|..., "detail": "..."}.
- A read-only key cannot call mutating tools.

For propose_inventory_item_change, pass concrete top-level arguments, not a wrapper:
inventory_type="hosts", item_id="bserv", mode="create", patch={"ip_address": "192.168.1.130", "user": "bserv"}, summary="Document bserv host".
The patch object is the inventory item fields to create or update.

Knowledge maintenance triggers:
- new host, VM, domain, endpoint, route, service, repository, device, credential reference, or dependency;
- changed IP address, port, upstream, status, operating system, version, owner, deployment path, or last-reviewed state;
- live observation contradicts documentation;
- user provides infrastructure facts in chat;
- agent discovers facts while connected to hosts, routers, APIs, GitBucket, or local services.

If a discovered fact is useful beyond the current chat and is not secret, it belongs in Gnexus Book. If you decide not to update it, say why.

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()


AGENT_USAGE_GUIDE = """
Gnexus Book MCP quick guide for agents:

Mission:
- Treat this MCP server as the owner's infrastructure memory.
- Use it before answering infrastructure-specific questions.
- Keep it current when durable facts are discovered.

Use it proactively for:
- hosts, VMs, VPS, routers, LANs, VPNs, domains, ports, routes, proxies;
- deployed services, smart-home, GitBucket repositories, project activity, source/deployment mapping;
- freshness, missing documentation, stale records, conflicting observations.

Read path:
1. search_docs(query)
2. read_doc(path)
3. list_inventory(inventory_type) or get_inventory_item(inventory_type, item_id)
4. get_relationships() for dependencies and routes
5. check_freshness() if age matters

Write path:
1. If a fact is durable, useful later, and non-secret, update docs/inventory.
2. Use propose_doc_change or propose_inventory_item_change for reviewable changes.
3. Use apply_pending_change, then validate_repository.
4. Use commit_changes with a concise factual summary.
5. Use update_doc only for simple full-document updates.

Inventory creation rule:
- When an inventory item requires a `docs` field, create the Markdown document first via propose_doc_change + apply_pending_change, then propose the inventory item.
- Never edit gnexus-book files directly through filesystem or terminal — always go through MCP tools.

Inventory write call shape:
- propose_inventory_item_change(inventory_type, item_id, patch, summary, reason?, mode?)
- Do not wrap arguments in params.
- For create mode, patch is the new inventory item fields.
- For update mode, patch is the fields to merge into the existing item.

Storage mode:
- In database mode, apply_pending_change publishes; commit_changes is a no-op.
- Use document_history, document_version, document_diff, and restore_document_version for version work.

Do document:
- hostnames, usernames, IPs, domains, ports, routes, access models, credential references, versions, repository activity.

Do not document:
- raw passwords, tokens, private keys, recovery codes, session cookies, secret config values.

End-of-task maintenance check:
- Did I learn a new durable infrastructure fact?
- Did I find stale or conflicting documentation?
- Did I update Gnexus Book or explicitly explain why not?
""".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))


def _docs():
    return make_docs_repository(_settings())


def _inventory():
    return make_inventory_repository(_settings())


def _pending():
    return make_pending_change_repository(
        _settings(),
        via="mcp",
        default_actor=Actor(kind="agent", via="mcp"),
    )


def _git() -> GitAdapter:
    return GitAdapter(_settings())


def _json(data: Any) -> str:
    return json.dumps(data, ensure_ascii=False, indent=2)


def get_agent_usage_guide() -> dict[str, str]:
    """Read the mandatory quick guide that tells agents when and how to use Gnexus Book MCP."""
    return {"guide": AGENT_USAGE_GUIDE}


def search_docs(query: str) -> list[dict[str, object]]:
    """Search canonical Markdown docs. Use this first for broad infrastructure lookup."""
    return _docs().search(query)


def read_doc(path: str) -> dict[str, object]:
    """Read one canonical Markdown document by repository-relative path after search/list discovery."""
    return _docs().read_doc(path)


def list_docs() -> list[dict[str, object]]:
    """List all canonical Markdown docs with titles and frontmatter."""
    return _docs().list_docs()


def list_inventory(inventory_type: str | None = None) -> object:
    """List inventory types or read parsed structured inventory such as hosts, services, domains, endpoints, projects, networks, hardware, or virtual-machines."""
    repo = _inventory()
    if inventory_type:
        return repo.read_parsed(inventory_type)
    return repo.list_types()


def get_inventory_item(inventory_type: str, item_id: str) -> dict[str, Any]:
    """Read one structured inventory record by type and id when you know the canonical id."""
    return _inventory().read_item(inventory_type, item_id)


def get_relationships() -> dict[str, object]:
    """Build the inventory relationship graph for dependencies, domains, upstreams, hosts, routes, and unresolved references."""
    return build_relationships(_inventory())


def validate_repository_tool() -> dict[str, object]:
    """Validate schemas, docs, duplicate ids, and raw secret patterns before trusting or committing changes."""
    settings = _settings()
    if settings.storage_backend == "db":
        return validate_database(Database.from_settings(settings))
    return validate_repository(settings)


def check_freshness() -> dict[str, object]:
    """Return freshness/staleness report for deciding what documentation needs review."""
    settings = _settings()
    if settings.storage_backend == "db":
        return build_freshness_report_db(Database.from_settings(settings))
    return build_freshness_report(settings)


def git_status() -> dict[str, Any]:
    """Return local Git status before editing or committing documentation changes."""
    return _git().status()


def git_diff(files: list[str] | None = None) -> dict[str, str]:
    """Return local Git diff, optionally limited to repository-relative files, for reviewing documentation changes."""
    return _git().diff(files)


def list_pending_changes() -> list[dict[str, Any]]:
    """List pending/applied/rejected/corrupt knowledge-change records created by agents."""
    return _pending().list()


def delete_pending_change(change_id: str) -> dict[str, Any]:
    """Delete one pending or corrupt knowledge-change record. Applied changes cannot be deleted."""
    return _pending().delete(change_id)


def propose_doc_change(
    path: Annotated[str, Field(description="Repository-relative Markdown path to create or replace, for example '10-systems/applications/gitbucket.md'.")],
    content: Annotated[str, Field(description="Full Markdown document content, including frontmatter when the target document uses it.")],
    summary: Annotated[str, Field(description="Short factual change summary used for the pending change and later commit message.")],
    reason: Annotated[str, Field(description="Why this change is needed; mention the source of the fact when useful.")] = "",
    is_user: Annotated[bool, Field(description="Set true only when the key owner explicitly acts as themselves; default actions are attributed to the agent.")] = False,
) -> dict[str, Any]:
    """Create a pending Markdown document change. Pass path, content, summary, and optional reason as top-level arguments."""
    denied = mcp_write_denied()
    if denied:
        return denied
    request = ProposedChangeRequest(
        kind="doc",
        target=path,
        summary=summary,
        reason=reason,
        payload={"content": content},
    )
    return _pending().create(request, actor=mcp_actor(is_user))


def propose_inventory_item_change(
    inventory_type: Annotated[str, Field(description="Inventory collection name, for example 'hosts', 'services', 'domains', 'networks', 'hardware', or 'virtual-machines'.")],
    item_id: Annotated[str, Field(description="Canonical inventory item id. For a host, use the stable host id such as 'bserv', not the IP address.")],
    patch: Annotated[dict[str, Any], Field(description="Inventory fields to create or update. For mode='create', this object is the new item body. Do not wrap it in 'inventory_item' or 'params'.")],
    summary: Annotated[str, Field(description="Short factual summary of the inventory change.")],
    reason: Annotated[str, Field(description="Why this inventory fact should be persisted; mention the source when useful.")] = "",
    mode: Annotated[Literal["update", "create"], Field(description="'create' for a new inventory item; 'update' to patch an existing item.")] = "update",
    is_user: Annotated[bool, Field(description="Set true only when the key owner explicitly acts as themselves; default actions are attributed to the agent.")] = False,
) -> dict[str, Any]:
    """Create a pending inventory change. Use top-level arguments: inventory_type, item_id, patch, summary, reason, mode."""
    denied = mcp_write_denied()
    if denied:
        return denied
    request = ProposedChangeRequest(
        kind="inventory-item",
        target=f"{inventory_type}/{item_id}",
        summary=summary,
        reason=reason,
        payload={"mode": mode, "patch": patch},
    )
    return _pending().create(request, actor=mcp_actor(is_user))


def apply_pending_change(change_id: str, is_user: bool = False) -> dict[str, Any]:
    """Apply one pending knowledge change and roll it back automatically if validation fails."""
    denied = mcp_write_denied()
    if denied:
        return denied
    return _pending().apply(change_id, actor=mcp_actor(is_user))


def commit_changes(
    summary: str, files: list[str], details: str = "", is_user: bool = False
) -> dict[str, Any]:
    """Validate the repository and create a local Git commit for selected documentation files."""
    denied = mcp_write_denied()
    if denied:
        return denied
    settings = _settings()
    if settings.storage_backend == "db":
        return {
            "status": "noop",
            "detail": "Database mode publishes changes when a changeset is applied; there is nothing to commit.",
        }
    return _git().commit(CommitRequest(summary=summary, details=details, files=files))


def update_doc(
    path: str, content: str, summary: str, reason: str = "", is_user: bool = False
) -> dict[str, Any]:
    """For simple full-document updates: create pending change, apply, validate, and commit in one call."""
    change = propose_doc_change(
        path=path, content=content, summary=summary, reason=reason, is_user=is_user
    )
    if "error" in change:
        return change
    change_id = str(change["id"])
    pending_path = f"90-maintenance/pending-changes/{change_id}.json"
    try:
        applied = apply_pending_change(change_id, is_user=is_user)
        if _settings().storage_backend == "db":
            return {
                "change": applied,
                "commit": {
                    "status": "applied",
                    "detail": "Database mode publishes the changeset on apply.",
                },
            }
        commit = commit_changes(
            summary=summary, files=[path, pending_path], details=reason
        )
    except Exception as exc:
        # Full rollback: never leave the pending file or draft changeset behind.
        try:
            delete_pending_change(change_id)
        except Exception:
            pass
        raise RuntimeError(
            f"update_doc failed; pending change {change_id} was cleaned up "
            f"(deleted if still pending). Original error: "
            f"{type(exc).__name__}: {exc}"
        ) from exc
    return {"change": applied, "commit": commit}


def document_history(path: str) -> list[dict[str, Any]]:
    """List document versions with author, actor, changeset, and summary metadata."""
    settings = _settings()
    if settings.storage_backend != "db":
        raise RuntimeError("Document history is available in database mode")
    return list_document_versions(Database.from_settings(settings), path)


def document_version(path: str, version_no: int) -> dict[str, Any]:
    """Read one document version by path and version number."""
    settings = _settings()
    if settings.storage_backend != "db":
        raise RuntimeError("Document versions are available in database mode")
    return get_document_version(Database.from_settings(settings), path, version_no)


def document_diff(
    path: str,
    from_version: int | None = None,
    to_version: int | None = None,
) -> dict[str, Any]:
    """Show a unified diff between two document versions; defaults to the latest pair."""
    settings = _settings()
    if settings.storage_backend != "db":
        raise RuntimeError("Document diff is available in database mode")
    return diff_document_versions(
        Database.from_settings(settings), path, from_version, to_version
    )


def restore_document_version(
    path: str, version_no: int, summary: str = "", is_user: bool = False
) -> dict[str, Any]:
    """Restore a document by creating a new version with the content of an older version."""
    denied = mcp_write_denied()
    if denied:
        return denied
    settings = _settings()
    if settings.storage_backend != "db":
        raise RuntimeError("Document restore is available in database mode")
    return restore_document_version_service(
        Database.from_settings(settings),
        settings,
        path,
        version_no,
        summary=summary or None,
        via="mcp",
        actor=mcp_actor(is_user),
    )


def build_transport_security(settings: Settings) -> TransportSecuritySettings:
    return TransportSecuritySettings(
        enable_dns_rebinding_protection=True,
        allowed_hosts=list(settings.mcp_allowed_hosts),
        allowed_origins=list(settings.mcp_allowed_origins),
    )


mcp = FastMCP(
    "gnexus-book",
    instructions=MCP_INSTRUCTIONS,
    host=os.environ.get("GNEXUS_BOOK_MCP_HOST", "127.0.0.1"),
    port=int(os.environ.get("GNEXUS_BOOK_MCP_PORT", "8001")),
    streamable_http_path="/mcp-protocol/",
    transport_security=build_transport_security(Settings()),
)


mcp.tool(name="search_docs")(search_docs)
mcp.tool(name="get_agent_usage_guide")(get_agent_usage_guide)
mcp.tool(name="read_doc")(read_doc)
mcp.tool(name="list_docs")(list_docs)
mcp.tool(name="list_inventory")(list_inventory)
mcp.tool(name="get_inventory_item")(get_inventory_item)
mcp.tool(name="get_relationships")(get_relationships)
mcp.tool(name="validate_repository")(validate_repository_tool)
mcp.tool(name="check_freshness")(check_freshness)
mcp.tool(name="git_status")(git_status)
mcp.tool(name="git_diff")(git_diff)
mcp.tool(name="list_pending_changes")(list_pending_changes)
mcp.tool(name="delete_pending_change")(delete_pending_change)
mcp.tool(name="propose_doc_change")(propose_doc_change)
mcp.tool(name="propose_inventory_item_change")(propose_inventory_item_change)
mcp.tool(name="apply_pending_change")(apply_pending_change)
mcp.tool(name="commit_changes")(commit_changes)
mcp.tool(name="update_doc")(update_doc)
mcp.tool(name="document_history")(document_history)
mcp.tool(name="document_version")(document_version)
mcp.tool(name="document_diff")(document_diff)
mcp.tool(name="restore_document_version")(restore_document_version)


@mcp.resource("gnexus-book://docs", mime_type="application/json")
def docs_resource() -> str:
    return _json(list_docs())


@mcp.resource("gnexus-book://agent-guide", mime_type="text/markdown")
def agent_guide_resource() -> str:
    return AGENT_USAGE_GUIDE


@mcp.resource("gnexus-book://docs/{path}", mime_type="application/json")
def doc_resource(path: str) -> str:
    return _json(read_doc(path))


@mcp.resource("gnexus-book://inventory", mime_type="application/json")
def inventory_resource() -> str:
    return _json(list_inventory())


@mcp.resource("gnexus-book://inventory/{inventory_type}", mime_type="application/json")
def inventory_type_resource(inventory_type: str) -> str:
    return _json(list_inventory(inventory_type))


@mcp.resource("gnexus-book://relationships", mime_type="application/json")
def relationships_resource() -> str:
    return _json(get_relationships())


@mcp.resource("gnexus-book://freshness", mime_type="application/json")
def freshness_resource() -> str:
    return _json(check_freshness())


@mcp.resource("gnexus-book://validation", mime_type="application/json")
def validation_resource() -> str:
    return _json(validate_repository_tool())


@mcp.resource("gnexus-book://git/status", mime_type="application/json")
def git_status_resource() -> str:
    return _json(git_status())


def main() -> None:
    transport = os.environ.get("GNEXUS_BOOK_MCP_TRANSPORT", "stdio")
    if transport not in {"stdio", "sse", "streamable-http"}:
        raise SystemExit("GNEXUS_BOOK_MCP_TRANSPORT must be stdio, sse, or streamable-http")
    if transport == "streamable-http":
        from .mcp_http import run

        run()
        return
    mcp.run(transport=transport)  # type: ignore[arg-type]


if __name__ == "__main__":
    main()