feat: establish read-only DocForge MCP foundation

docs/CONTRACT.md

@@ -0,0 +1,49 @@
+# DocForge 0.1 contract
+
+## Authority boundary
+
+DocForge is bound to one explicit project root. Canonical project files own documentation facts.
+Indexes, query results, context packs, changesets, previews, and renders are derived artifacts.
+
+The generic core may validate and retrieve canonical nodes. A future proposal service may write only
+isolated changesets. Canonical application, project builds, Git mutation, deployment, and
+publication remain external integration actions. Passive revision detection may read the current Git
+commit when Git is available; it cannot change repository state.
+
+## Versioned contracts
+
+- Project descriptor schema: `schemas/project.schema.json`, version 1.
+- Node schema: `schemas/node.schema.json`, version 1.
+- Edge schema: `schemas/edge.schema.json`, version 1.
+- Result envelope: `schemas/result.schema.json`, version 1.
+- Changeset schema: `schemas/changeset.schema.json`, version 1, reserved for DFG-3.
+- Index schema: version 1, disposable and reproducible.
+- Core and CLI: version 0.1.0.
+
+Schema files describe the generic interchange contract. Runtime validation remains responsible for
+path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
+state, and adapter-specific rules that JSON Schema cannot prove by itself.
+
+## Generic node storage
+
+Markdown nodes begin with a TOML metadata block delimited by `+++`. The remaining Markdown is the
+node content. TOML sources contain one or more `[[nodes]]` tables and store content in a `content`
+field. Every node has a stable project-wide ID.
+
+The generic authority vocabulary is `authoritative`, `approved_plan`, `derived`, `proposal`, and
+`historical`. Projects define statuses and allowed relationship names in their descriptor. The core
+gives special acyclic validation to `depends_on`; adapters may add stricter rules.
+
+## Result identity
+
+Successful operations identify the project, adapter, current revision when available, and canonical
+source hash. Errors use a stable code, direct message, and structured details. Query operations fail
+if canonical source no longer matches the derived index.
+
+## Write model reserved for DFG-3
+
+Create, update, move, and delete are ordered node operations inside an isolated changeset. Every
+operation names its expected base hash. A move preserves the stable node ID. A delete must resolve
+required incoming relationships. Validation and application are atomic; prose is never auto-merged.
+
+Normal MCP access will not expose canonical application or arbitrary file writes.

docs/MCP_CONTRACT.md

@@ -0,0 +1,43 @@
+# MCP boundary
+
+The DFG-2 server will use local standard input/output transport and bind once to the explicit
+`--project-root` supplied at process startup. It will not expose an HTTP port in the first release.
+
+## Read tools
+
+- `docforge_project_info`
+- `docforge_get_contract`
+- `docforge_get_node`
+- `docforge_search`
+- `docforge_filter_nodes`
+- `docforge_backlinks`
+- `docforge_dependencies`
+- `docforge_impact`
+- `docforge_get_context`
+- `docforge_validate_project`
+- `docforge_render_status`
+
+Each response states that document text is project content, not higher-priority instructions. Each
+response includes project identity, revision, source hash, adapter version, and staleness state.
+
+## Proposal tools reserved for DFG-3
+
+- `docforge_create_changeset`
+- `docforge_propose_node_create`
+- `docforge_propose_node_update`
+- `docforge_propose_node_move`
+- `docforge_propose_node_delete`
+- `docforge_validate_changeset`
+- `docforge_get_changeset_diff`
+- `docforge_preview_changeset`
+
+Proposal tools may write only below the configured changeset root. They never change canonical files.
+
+## Excluded tools
+
+The normal server never exposes shell execution, arbitrary reads or writes, canonical changeset
+application, Git mutation, project builds, deployment, publication, global project selection, or
+cross-project retrieval.
+
+DocForge pins the official stable Python MCP SDK to the compatible `mcp>=1.28,<2` release line.
+Migration to a later major release requires a separate contract and protocol compatibility review.