# vineverse-mcp

[![CI](https://github.com/DataCraftsmanAU/vineverse-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/DataCraftsmanAU/vineverse-mcp/actions/workflows/ci.yml)

[![vineverse-mcp MCP server](https://glama.ai/mcp/servers/DataCraftsmanAU/vineverse-mcp/badges/card.svg)](https://glama.ai/mcp/servers/DataCraftsmanAU/vineverse-mcp)

A stdio bridge to the hosted [VineVerse](https://vineverse.bible/mcp) MCP server — the Bible
as a knowledge graph.

**If your client speaks streamable HTTP, you do not need this package.** Point it straight at
the endpoint:

```
https://vineverse.bible/api/mcp
```

No API key, no account. This package exists for clients that can only launch a local
process, and it does nothing except carry JSON-RPC messages between that process and the
hosted server.

## Install

```jsonc
// claude_desktop_config.json, or any client's equivalent
{
  "mcpServers": {
    "vineverse": {
      "command": "npx",
      "args": ["-y", "github:DataCraftsmanAU/vineverse-mcp"]
    }
  }
}
```

Or with Docker:

```bash
docker build -t vineverse-mcp .
docker run -i --rm vineverse-mcp
```

Node 20 or newer. There are no dependencies.

## What is behind it

One immutable corpus in [Open Knowledge Format](https://vineverse.bible/about), built from
public-domain Scripture and openly licensed scholarship. `get_stats` returns the exact
document count and every collection; the figures below are the ones that do not drift:

| | |
|---|---|
| Scripture | 31,102 verses of the Berean Standard Bible, 1,189 chapters, 66 books |
| People | ~3,000, with recorded kinship |
| Places | ~1,300, with coordinates |
| Themes | ~3,000, from Nave's Topical Bible |
| Lexemes | ~2,900 Strong's Hebrew entries, with interlinear alignment |
| Law | the 613 commandments |
| Narrative | ~450 events across ~165 dated epochs on Ussher's chronology |
| Graph | 90,564 connections between documents — 147,002 directed edges |

Sources and their licences are listed at
[vineverse.bible/attribution](https://vineverse.bible/attribution). The MIT licence on this
repository covers the bridge, not the corpus.

## Tools

17, unchanged from the hosted server — this package neither adds nor filters any.

| Tool | What it does |
|---|---|
| `search_concepts` | Search every document by name, description, tag, path and type |
| `search_scripture` | Full-text search across all 31,102 verses |
| `get_passage` | A verse, verse range or whole chapter by OSIS reference |
| `get_interlinear` | The Hebrew, Aramaic or Greek behind the English, word by word |
| `find_cross_references` | Cross references for a verse or chapter, ordered by crowd support |
| `get_entity` | Any document by path — `people/moses`, `places/bethel-1`, … |
| `get_family` | Parents, children, siblings and spouses, to any depth |
| `find_places_near` | Biblical places within a radius, nearest first, in km |
| `get_connections` | The shape of the cross-reference corpus — hubs, clusters, bridges |
| `get_graph_neighborhood` | Everything within N hops of a document, with the predicate on each edge |
| `list_documents` | Browse or page through any collection |
| `get_stats` | Every collection with its document count, folder and an example path |
| `get_vocabulary` | The closed predicate set every typed edge is drawn from |
| `get_tags` | Every tag with the number of documents carrying it |
| `get_changelog` | The knowledge base's own log, and when the data was ingested |
| `get_status` | Availability over the last 24/30/90 days, and which optional datasets are built |
| `get_support` | Who runs the site, what it costs to run, and the donation link |

## Resources

The server advertises one resource, `vineverse://support` — who runs it, what it costs, and
where the surplus goes. It is annotated `audience: ["user"]`, which is the spec's way of
saying it is addressed to the human rather than the model. Like the tools, it is forwarded
untouched, so a stdio client that reads resources will see it too.

## Funding

VineVerse is free, keyless and ad-free, and it runs on donations. MCP traffic reaches the
endpoint but rarely the site itself, so someone who only ever talks to a client may never see
a link to it. `get_support` and `vineverse://support` close that gap: the server states that
the site is donation-funded, and the model hands the link at
[vineverse.bible/support](https://vineverse.bible/support) to the person who can actually
give.

## Configuration

| | |
|---|---|
| `VINEVERSE_MCP_URL` | Endpoint to bridge to. Defaults to `https://vineverse.bible/api/mcp` |

Useful for running against a local checkout of the site:

```bash
VINEVERSE_MCP_URL=http://localhost:3100/api/mcp node index.js
```

## Test

```bash
npm run build   # syntax check — there is nothing to compile
npm test
```

The test spawns the bridge as a real child process rather than importing the module, because
two of the four things being checked — that a notification draws no reply, and that the
process exits 0 without truncating a response — are properties of the process, not of any
function in it. It drives `initialize`, `notifications/initialized` and `tools/list` over
real stdio, then a `get_passage` call for John 3:16. It talks to the live endpoint, so a
failure means either the bridge or the hosted server.

CI runs both on every push and weekly on a schedule, against Node 20 and 24. The scheduled
run is deliberate: because the test talks to the live endpoint, a green badge on a repository
that has not changed in months still means the server answers today.

`build` exists because hosted builders (Glama among them) run `install` then `build`
unconditionally. Rather than a no-op, it runs `node --check`, which is the only meaningful
build step a dependency-free single file has.