SectionSource Self-Hosted MCP Implementation Spec

Simple Summary

This phase implements the self-hosted MCP tool for body-free SectionSource v0 metadata.

The implementation registers only the local self-hosted MCP tool. It keeps hosted MCP, Hub routes, search, persistence, Scooling runtime behavior, section bodies, snippets, summaries, PageIndex, OCR, LLM calls, and provider routing blocked.

Technical Summary

The self-hosted MCP tool exposes the existing readSectionSource behavior through a single note-scoped read tool. It mirrors the self-hosted get_note_outline, get_document_tree, and get_metadata_facets tools:

• load local config
• accept exactly one vault-relative note path
• call resolveVaultRelativePath
• read one note through the existing local note-read path
• return body-free SectionSource v0 metadata
• return MCP JSON errors for missing notes, traversal paths, and runtime failures

Proposed Tool

get_section_source

The tool name is accepted only for the self-hosted MCP implementation phase. It is not accepted for hosted MCP, Hub routes, search, persistence, or Scooling runtime consumption.

Input Schema

The tool accepts:

{
  "path": "inbox/example.md"
}

Field rules:

• path is required.
• path must be a string.
• path must be vault-relative.
• path must not be absolute.
• path must not escape the vault.
• No batch paths are accepted.
• No body, snippet, search, filter, ranking, provider, or Scooling options are accepted.

Accepted Output

The tool returns exactly the existing body-free SectionSource v0 shape:

{
  "schema": "knowtation.section_source/v0",
  "path": "inbox/example.md",
  "title": "Example",
  "sections": [
    {
      "section_id": "inbox-example-md:h1-example-0001",
      "heading_id": "h1-example-0001",
      "level": 1,
      "heading_path": ["Example"],
      "heading_text": "Example",
      "child_section_ids": [],
      "body_available": true,
      "body_returned": false,
      "snippet_returned": false
    }
  ],
  "truncated": false
}

Explicitly Excluded Output

The tool must not output:

• note body text
• section body text
• snippets
• source excerpts
• full frontmatter
• absolute filesystem paths
• exact line ranges
• byte offsets
• section body lengths
• summaries
• vector scores
• provider payloads
• MCP resource URIs
• search results
• persistence ids
• Scooling adapter state

Error Behavior

The tool must:

• fail when path is missing
• fail when path is not a string
• fail for traversal paths before note reads
• fail for missing notes using the same local note-read behavior as adjacent self-hosted read tools
• return MCP JSON errors with RUNTIME_ERROR
• not include note body text, snippets, full frontmatter, or absolute paths in errors

Authorization And Path Safety

The tool preserves the self-hosted local note-read boundary:

• the caller may only read notes available through the configured local vault
• paths must be vault-relative
• absolute paths are rejected
• traversal paths are rejected before note reads
• symlinks that escape the vault remain blocked by existing vault behavior
• missing and unauthorized note behavior must not reveal more than get_note_outline, get_document_tree, or get_metadata_facets

Transport Boundaries

This phase implements only the self-hosted MCP tool.

It does not approve:

• hosted MCP
• Hub REST
• OpenAPI
• Hub UI
• canister routes
• search
• persistence or sidecars
• Scooling runtime consumption
• section bodies
• snippets
• summaries
• PageIndex
• OCR
• LLM calls
• external provider routing

Resource Boundary

The self-hosted MCP tool must not expose an MCP resource URI for section sources, section bodies, snippets, or derived section records.

SectionSource metadata must remain a tool response only until a separate resource contract is accepted.

Seven-Tier Test Requirements

Unit

• The tool name and required path field are documented.
• The output field allowlist matches SectionSource v0.
• body_returned and snippet_returned remain false.

Integration

• The tool uses the existing config, path validation, and note-read behavior.
• Missing and traversal paths fail consistently with adjacent body-free MCP tools.
• The tool output matches readSectionSource for the same note.

End To End

• A self-hosted MCP client can request one note's body-free section candidates.
• No MCP flow returns section body text or snippets.
• No MCP resource URI is exposed for section source content.

Stress

• Large notes remain capped by heading count and input caps.
• Large outputs remain bounded by section count and text caps.
• Repeated calls are deterministic for unchanged notes.

Data Integrity

• The tool does not write notes, sidecars, indexes, vectors, memory, summaries, or canister state.
• The tool reflects current note content only.
• No cached section record is created.

Performance

• The tool reads one note only.
• The tool does not scan the whole vault.
• The tool does not call external providers.

Security

• No note body text appears in output.
• No section body text appears in output.
• No snippets appear in output.
• No full frontmatter appears in output.
• No absolute filesystem paths appear in output.
• No MCP resource URI appears in output.
• Prompt-injection text remains untrusted source material.
• Hosted, Scooling, classroom, search, and persistence exposure remain blocked.

Stop Conditions

Stop and re-plan if implementation requires:

• returning note body text
• returning section body text
• returning snippets
• returning exact line ranges
• returning byte offsets
• returning section body lengths
• adding summaries
• adding search, vectors, indexes, persistence, sidecars, or memory events
• adding hosted MCP, Hub REST, OpenAPI, Hub UI, canister routes, or Scooling runtime code
• sending note-derived content to LLMs, OCR, PageIndex, or external providers
• weakening existing local note-read behavior

Acceptance Criteria

This implementation is accepted when:

• It registers the get_section_source tool name in self-hosted MCP.
• It requires one vault-relative note path.
• It limits output to body-free SectionSource v0 metadata.
• It preserves local note-read path and authorization behavior.
• It blocks MCP resources for section source content.
• It keeps hosted, Hub, search, persistence, Scooling, body, snippet, provider, OCR, PageIndex, and LLM behavior blocked.
• Tests prove the runtime MCP tool is body-free and no blocked transport or provider surface was added.

Recommendation

Phase 1G is complete when tests prove get_section_source returns body-free SectionSource v0 output and all blocked surfaces remain absent.

The next hosted-facing step is accepted separately in docs/SECTION-SOURCE-HOSTED-AUTHORIZATION-REVIEW-SPEC.md. Do not add hosted runtime exposure without a hosted implementation spec and seven-tier tests.

The Scooling consumer boundary is accepted separately in docs/SECTION-SOURCE-SCOOLING-ADAPTER-PLANNING-SPEC.md. Do not add Scooling runtime consumption without a Scooling implementation slice and seven-tier tests.

The Scooling implementation slice is complete in the Scooling repository at commit ea5421e (Add Scooling SectionSource transport boundary).