# GetBible MCP 2.0

Read-only MCP access to all nine GetBible API contracts. The protocol endpoint is /mcp; a consuming
application supplies its public URL. Local transport: getbible-mcp --transport stdio. Both transports
have the same tools, resources and prompts. Python MCP SDK 2.2.0 implements protocol 2026-07-28.

## Start here

- discover_apis: service/version catalog and authoritative OpenAPI URLs.
- describe_api_operation: list operations or inspect one operation's exact inputs/outputs/errors.
- call_api_operation: execute a described read-only operation, including search POST.
- resources/read getbible://docs/api: full integration guide.
- resources/read getbible://openapi/{service}/{version}: complete packaged OpenAPI contract.
- design_getbible_integration: integration planning prompt.

Services: api (v2/v3), query (v2/v3), search (v2/v3), dictionaries (v1), commentaries (v1),
bookmarks (v1). Operation IDs and argument names are scoped to the selected service/version.
Use parameters keyed by input_name; query.<name> disambiguates a name also used in the path.

## Convenience tools

- list_translations, list_books, list_chapters: discover metadata and valid coordinates.
- get_scripture: whole translation/book/chapter with before/after scope SHA-1 checks.
- query_verses: selected or grouped references; no fallback passage for invalid/missing references.
- search_verses: full-text search and upstream filters/pagination.
- get_hash, get_hash_manifest, check_for_updates: static scripture synchronization.
Scripture tools default api_version to v3. Choose v2 explicitly for upstream v2 data.

## Data and cache rules

Preserve native JSON and unknown fields. V3 tokens, spans, paragraph markers and lexical data must
not be flattened to v2. Retrieve rich translation metadata and rights from translation catalogs.
Discover dictionary IDs, entry IDs and commentary coverage; chapter/verse 0 can be introductions.
Bookmarks are public topics/references without scripture text or personal write operations.

The MCP keeps no persistent result cache. Query/search are non-cacheable by default. Downstream
caches must never exceed 30 days (2592000 seconds) and must obey shorter HTTP freshness, Age,
Expires, no-cache and no-store. Query/search TTL comes from HTTP headers, not a promised JSON field.
Search query.sha/query.cache are source/engine metadata, not result checksums. Static scripture uses
SHA-1; dictionary/commentary/bookmark manifests use SHA-256. Refresh atomically when hashes change.
Honor each translation/module's rights and provenance; the MCP software GPL does not relicense data.

## Documentation

This directory documents MCP package 2.0 and every supported upstream API version.

- Guide: api.md
- Examples: examples.md
- Cache policy: cache-policy.md
- Usage policy: usage-policy.md
- Manifest: manifest.json
- Tool catalog: tool-catalog.json

## Authoritative upstream OpenAPI documents

- https://api.getbible.net/v2/openapi.json
- https://api.getbible.net/v3/openapi.json
- https://query.getbible.net/v2/openapi.json
- https://query.getbible.net/v3/openapi.json
- https://search.getbible.net/v2/openapi.json
- https://search.getbible.net/v3/openapi.json
- https://dictionaries.getbible.net/v1/openapi.json
- https://commentaries.getbible.net/v1/openapi.json
- https://bookmarks.getbible.net/v1/openapi.json

Exact static copies: ../contracts/{service}-{version}.json
