Schema版本控制工具包

panproto-toolkit

Written for panproto v0.71.0. See keeping up to date for version tracking.

Claude Code skills, agents, an MCP server, project templates, and CI integrations for working with panproto, the schematic version control engine.

panproto treats every schema language (ATProto, OpenAPI, Protobuf, GraphQL, Avro, SQL DDL, and 43 others) as a view over a single graph format, and can also parse source code in 261 programming languages via tree-sitter. The same diff/migrate/version-control workflow works on data schemas, API specs, config files, and code structure.

Quick install

curl -sSf https://raw.githubusercontent.com/panproto/panproto-toolkit/main/install.sh | bash

This clones the repo, symlinks the skills, CI integrations, and agents into your ~/.claude/ directory, and builds and registers the MCP server. Pass --no-mcp to skip the last step.

Prerequisites

• Claude Code CLI or IDE extension
• panproto CLI (schema): brew install panproto/tap/panproto-cli or cargo install panproto-cli

What's in the box

Skills

Invoke any skill in Claude Code with /panproto-<name>.

Core workflow

Advanced

SDK guides

CI integration

Contributing

Agents

Specialized sub-processes that Claude Code delegates to for focused analysis.

MCP server

The @panproto/mcp-server package exposes panproto operations to any MCP-compatible client (Claude Desktop, VS Code, other AI tools).

npm install -g @panproto/mcp-server

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "panproto": {
      "command": "panproto-mcp-server"
    }
  }
}

Security and approvals

Every tool is classified by risk level and annotated with MCP tool hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint):

• Read-only (47 tools): analysis, inspection, diffing, validation. Auto-approved.
• Write-additive (10 tools): VCS init/add/commit, enrichment additions, branch/tag creation. Auto-approved.
• Write-destructive (15 tools): data migration, VCS merge/rebase/reset, git import/export. Gate on MCP elicitation-based user approval before executing.

All invocations are recorded in a session-scoped audit log accessible via panproto_session_audit.

72 tools across 13 categories

6 prompts

3 resources

See mcp-server/README.md for full documentation.

Templates

Project scaffolds for getting started quickly:

• templates/ts-project/ : TypeScript project with @panproto/core ^0.71.0
• templates/python-project/ : Python project with panproto>=0.71.0
• templates/rust-project/ : Rust project with panproto-core 0.71.0 (edition 2024, rust-version 1.85)
• templates/swift-project/ : Swift package depending on panproto 0.71.0 through the panproto-swift mirror (Swift 6.1, macOS 14 and iOS 17)
• templates/github-actions/ : CI workflow templates

Learning path

If you are new to panproto, work through the skills in this order:

1. /panproto-getting-started to scaffold a project
2. /panproto-define-schema to learn schema construction
3. /panproto-build-migration to migrate between schema versions
4. /panproto-use-lenses for bidirectional transforms
5. /panproto-schema-vcs for version control
6. /panproto-breaking-change-ci to protect your schemas in CI

Each skill references chapters in the panproto book (Diataxis-organized: tutorials, how-to guides, reference, explanation). See docs/tutorial-map.md for the mapping.

What changed in panproto 0.71.0

Two things in this release reshape what the toolkit tells you to do, so they are worth reading before following a plan written against an older version.

The morphism search returns a span. find_span answers with src <- apex -> tgt, whose apex is the sub-schema of the source induced on the vertices that found a target. It never refuses for want of a match: two schemas with nothing in common come back with an empty apex rather than a failure, which on real schema pairs is the common answer, since most admit no total morphism at all. schema auto-migrate reports the apex size, the coverage fraction, and the interval the search proved the quality lies in; --total, the default, and --span are three rungs of one strictness ladder over that one search. The span surface reaches every binding: find_span in Python, Panproto.span in TypeScript, SchemaHandle.findSpan in Swift, pp_hom_find_span on the C ABI.

Any threshold calibrated before 0.71.0 needs re-reading. Quality now comes out of the objective the search minimised rather than a separate scorer, and its Jaccard component's normaliser changed, so the same morphism can report a different number. find_morphisms returns the morphisms attaining the optimum rather than the whole hom-set, and its cap bounds every request. A search that could not be posed, or that spent its budget, is reported as such instead of arriving as "no morphism exists".

Alongside those: the overlap between two schemas is now the maximum common induced sub-schema, RecursionPoint::mu_id is gone, SearchOptions::initial is now hard_pins, and SearchOptions::preferred, max_nodes, relax_edge_name_pruning, and DomainConstraints::name_similarity_threshold are removed.

One standing limit worth stating beside them, unchanged by this release: the schema CLI resolves a single protocol, atproto. Every command taking --protocol exits with unknown protocol on any other name. All 54 built-ins are reachable through the SDKs, which read the same registry.

Keeping up to date

This toolkit is written for a specific panproto version. When panproto releases a new version:

1. Check the panproto CHANGELOG for API changes
2. Run git pull in your panproto-toolkit clone to get updates
3. The MCP server version tracks the toolkit version

To update:

cd ~/.local/share/panproto-toolkit && git pull
npm update -g @panproto/mcp-server

License

MIT