Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
42cfd29
feat(kg): read-only MCP server over the exported graph
Sulstice Nov 9, 2026
a662861
ci(kg): run the MCP server tests in the KG gate; publish the graph file
Sulstice Nov 9, 2026
33c32ed
feat(kg): rank by spreading activation: find_related, and strength on…
Sulstice Nov 10, 2026
cfcef47
fix(kg): revise the ranking after review: leaner replies, truer docs
Sulstice Nov 12, 2026
cc89b2d
feat(kg): benchmark the MCP server with the competency questions
Sulstice Nov 12, 2026
8f0d2e7
feat(kg): benchmark all 42 competency questions, the 23 proposed in #…
Sulstice Nov 12, 2026
25220e0
test(kg): hold the benchmark walks to five more shapes
Sulstice Nov 12, 2026
82e4545
fix(kg): act on the fourth review: arguments, limits, replies, the re…
Sulstice Nov 12, 2026
3a91efe
fix(kg): act on the review of the review fixes
Sulstice Nov 12, 2026
5afb97d
feat(kg): serve the MCP server on a public URL; last review's fixes
Sulstice Nov 12, 2026
34c7c10
feat(kg): Inspector Publications and Meetings tabs
Sulstice Nov 16, 2026
2f1a763
chore(kg): rebuild the Inspector; guard the meeting notes off it
Sulstice Nov 16, 2026
f0679b4
feat(kg): the Inspector asks all 42 competency questions
Sulstice Nov 16, 2026
02e55c1
chore(kg): rebuild the Inspector with all 42 questions
Sulstice Nov 16, 2026
abebe2e
feat(kg): adopt CQ20-CQ42 into the questions the KG is scored on (#441)
Sulstice Nov 16, 2026
584d06d
chore(kg): rebuild the Inspector with the 42 adopted questions
Sulstice Nov 16, 2026
599c40f
feat(kg): Inspector Devices tab from the consortium device list
Sulstice Nov 16, 2026
f2f8b83
chore(kg): rebuild the Inspector with the Devices tab code
Sulstice Nov 16, 2026
68d34cf
fix(kg): act on the review of the Inspector tabs
Sulstice Nov 16, 2026
d419b2c
chore(kg): rebuild the Inspector after the review fixes
Sulstice Nov 16, 2026
06522fc
feat(kg): export which device categories each project uses, and every…
Sulstice Nov 16, 2026
bb61aaf
chore(kg): rebuild the Inspector with CQ14 modelled
Sulstice Nov 16, 2026
ea1175c
feat(kg): a Graph tab in the Inspector to see and walk the graph in 2D
Sulstice Nov 16, 2026
48535c1
feat(kg): redesign the Graph tab for looking around: map first, then …
Sulstice Nov 16, 2026
1aed154
fix(kg): the 29 review findings on the redesigned Graph tab
Sulstice Nov 16, 2026
921c72e
feat(kg): link, don't copy; call the shapes SHACL validation; gate du…
Sulstice Nov 17, 2026
8986039
feat(db): one script that links or removes the isolated nodes (under …
Sulstice Nov 17, 2026
4ade938
fix(db): isolated-nodes script — the 15 review findings and 6 verific…
Sulstice Nov 17, 2026
b10e648
chore(kg): re-export after link_isolated_nodes — 76 of 758 nodes isol…
Sulstice Nov 17, 2026
0a29c8f
fix(db): fill the funding calls' missing expiration dates (CQ39; lets…
Sulstice Nov 17, 2026
567f682
fix(security): visitors could write through the public views; revoke it
Sulstice Nov 17, 2026
73b9417
feat(kg): jobs on the public export: CQ18, CQ35, CQ36, CQ37 answerabl…
claude Nov 17, 2026
b7c6044
feat(dedup): refuse duplicates when they are written, and link prepri…
Sulstice Nov 17, 2026
6b81261
fix(security): anon could read e-mails, auth user ids and review note…
claude Nov 17, 2026
65b5b7a
fix(dedup): review of b7c6044: a URL is no identity, versions paired …
claude Nov 17, 2026
958f959
fix(dedup): a URL or a name alone never makes two records one; say a …
claude Nov 17, 2026
82b02ac
fix(kg): a column the database lacks costs that column, not the whole…
Sulstice Nov 18, 2026
925e9e3
chore(kg): export of 2026-11-18 — job posters, call expiry dates, the…
Sulstice Nov 18, 2026
b661f38
fix(security): hotfix — anonymous visitors could add a sign-in addres…
Sulstice Nov 18, 2026
9600b2a
fix(dedup): order versions by PubMed id, not a drifting year; a name …
claude Nov 18, 2026
7fb8274
fix(privacy): every public function says who may run it; anon loses t…
claude Nov 18, 2026
d01a936
chore(kg): rebuild the report and the public Inspector after the dedu…
Sulstice Nov 18, 2026
ae2f17e
fix(people): a column production lacks must not take the People page …
Sulstice Nov 18, 2026
faf5ced
feat(roles): 'collaborator' is a project role; every role menu is hel…
Sulstice Nov 18, 2026
8b637dc
fix(privacy): public project details do not depend on a migration tha…
Sulstice Nov 19, 2026
4771c41
fix(kg): date the committed export by epoch seconds, so every git and…
Sulstice Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .github/workflows/kg.yml
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,19 @@ jobs:
if: steps.scope.outputs.run == 'true'
run: python kg/ci_check.py --check-generated

# kg/bbqs_kg.py's export() against a stand-in for Supabase's REST API: no network, no key.
- name: Exporter tests
if: steps.scope.outputs.run == 'true'
run: python kg/test_exporter.py

# kg/mcp_server.py: the traversal answers, the read-only guarantee, and the protocol itself
# (a real server process over stdio and HTTP). Adds the MCP SDK to the environment above.
- name: MCP server tests
if: steps.scope.outputs.run == 'true'
run: |
pip install -r kg/requirements-mcp.txt
python kg/test_mcp_server.py

- name: Quality summary
if: steps.scope.outputs.run == 'true' && always()
run: |
Expand Down
5 changes: 5 additions & 0 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,11 @@ jobs:
pip install -r kg/requirements.txt
if python kg/export.py /tmp/live.ttl; then
data=/tmp/live.ttl; src="live anon export (daily build)"
# The graph itself -> dist/kg/bbqs.ttl, the default source of kg/mcp_server.py. The same
# anon export the Inspector embeds, so it publishes nothing that page does not. Only a
# live export goes out: the file's date is how a reader knows the age of the data, and
# the committed fallback would carry today's date on old data.
mkdir -p dist/kg && cp "$data" dist/kg/bbqs.ttl || echo "::warning::kg/bbqs.ttl was not published"
else
data=kg/export/bbqs.ttl; src="committed kg/export/bbqs.ttl (live export failed)"
fi
Expand Down
9 changes: 9 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,12 @@ supabase/.temp/

# The weekly digest the progress builder writes next to its JSON snapshot; only the JSON is served.
public/data/progress.md

# Internal: the working-group notes and the device list, and what kg/meetings.py and kg/devices.py
# build from them, live outside the repo (tests/guards/inspector-internal-data checks for them too).
meetings_extracted.json
meetings_flat.csv
person_roles.csv
device_evidence.csv
device_discussion_crosscutting.csv
bbqs_devices_kg.json
15 changes: 14 additions & 1 deletion DATABASE_DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,10 +137,23 @@ Consortium project metadata. Each project is linked to a grant via `grant_id`.
| `study_species` | `text[]` | Yes | `{}` | Species studied |
| `study_human` | `boolean` | Yes | `false` | Human subjects flag |
| `website` | `text` | Yes | — | Project website |
| `last_edited_by` | `text` | Yes | — | Email of last editor |
| `last_edited_by` | `text` | Yes | — | Email, auth user id or actor label of the last editor. **Not readable by anon** |
| `questionnaire_submitted_by` | `text` | Yes | — | Email of the Data Questionnaire respondent. **Not readable by anon** |
| `questionnaire_submitted_at` | `timestamptz` | Yes | — | When that response was submitted. **Not readable by anon** |
| `questionnaire_response_id` | `text` | Yes | — | Google Forms responseId. **Not readable by anon** |
| `created_at` | `timestamptz` | No | `now()` | — |
| `updated_at` | `timestamptz` | No | `now()` | — |

**Anon reads named columns only** (20261117190000): anon may SELECT every column above except the four
marked, so an anonymous `select=*` is refused. The questionnaire attribution was three keys inside
`metadata` until then; `trg_aa_keep_questionnaire_attribution_private` moves them into the columns on
every write. The same column-by-column rule covers `investigators_public` (no `user_id`, `pending_role`),
`feature_suggestions_public` (no `submitter_name`, `github_username`), `resources.created_by`,
`announcements.posted_by`, `entity_comments.user_id`, `dandisets` (`raw`, `hidden_reason`, `hidden_by`,
`hidden_at`), `harvester_relations.approved_by` and `harvester_settings.updated_by`; anon may not read
`project_questionnaire_status` at all. A column added later is hidden from anon until a migration runs
`GRANT SELECT (<column>) ON public.<object> TO anon` (tests/guards/anon-private-columns).

### `investigators`

Principal investigators and co-PIs across the consortium.
Expand Down
104 changes: 104 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,110 @@ Green badge = live, red = dead.
| **Tutorials** | Learning materials for consortium tools and workflows |
| **Job Board & Calendar** | Community job postings and upcoming events |

## Knowledge graph over MCP

The consortium's public knowledge graph (projects, people, working groups, organizations, species, publications) can be read by Claude and other AI clients through a small read-only [MCP](https://modelcontextprotocol.io) server, [`kg/mcp_server.py`](kg/mcp_server.py). It loads the exported graph into memory and answers from that: no database, no sign-in, no write path. What is related to what is ranked by spreading activation, the account in psychology of how one idea brings up another; [`kg/README.md`](kg/README.md#how-it-decides-what-is-related) states the rule and works an example by hand.

Check that it loads, then ask it the consortium's own questions:

```bash
uv run kg/mcp_server.py --check
```

```bash
uv run kg/bench_mcp_server.py
```

The second command starts the server the way a client does and asks it the [42 competency questions the graph is scored on](kg/competency_questions.yaml) (CQ20-CQ42 adopted from #441). Each is asked twice, once as SPARQL and once without SPARQL through the graph tools, and both are checked against the export queried directly. It then measures the ranking and the speed. `--show CQ04` prints one question's rows; `--only questions` skips the measurements. Without [uv](https://docs.astral.sh/uv/), run `pip install -r kg/requirements.txt -r kg/requirements-mcp.txt` and use `python` in place of `uv run`.

To talk to it from Claude Code (give the full path to your checkout):

```bash
claude mcp add bbqs-kg -- uv run /path/to/bbqs-app/kg/mcp_server.py
```

Or, with no checkout at all, straight from GitHub:

```bash
claude mcp add bbqs-kg -- uv run https://raw.githubusercontent.com/brain-bbqs/bbqs-app/main/kg/mcp_server.py
```

To serve it on a public URL for a claude.ai connector, see [On a public URL](kg/README.md#on-a-public-url).

### Benchmark

<!-- kg-mcp-benchmark:start -->
Graph: 653 nodes, 973 links, export of 2026-11-18. Server 0.2.0.

| | Result |
|---|---|
| Competency questions that return rows on this export | **34 of 42** |
| Those 34, asked as SPARQL through the server: same rows as the export queried directly | **34 of 34** |
| Those 34, asked without SPARQL through the graph tools: same rows again | **34 of 34** |
| The other 8 (3 need the full export, 5 find none in this export): no rows either way | **8 of 8** |
| Hide a real tie: the hidden end is among the first ten `find_related` lists after the start's direct ties (1,696 cases) | **67%** (68% looking up to 8 links) |
| The same for `get_neighbors`, which lists by distance alone | 50% (52% walking through hubs) |
| Strengths equal to a slow second version of the rule, exactly | **581 of 581** starting nodes |
| A `find_related` call (median; 95th percentile) | 12 ms; 18 ms |
| A `find_paths` call | 7 ms; 15 ms |
| A `find_related` reply (median; largest of the 117 timed) | 13.9 kB; 18.4 kB |

<details><summary>All 42 questions, both ways</summary>

| | Question | Rows | As SPARQL | Without SPARQL | How, without SPARQL |
|---|---|---:|:---:|:---:|---|
| CQ01 | Which projects are in the consortium, with grant number and mechanism? | 33 | same | same | list the projects; read each one's properties |
| CQ02 | What is the total award amount per mechanism? | 5 | same | same | list the projects; add up their awards by mechanism |
| CQ03 | Which institution hosts each project? | 3 | same | same | from each project, the organization one link away |
| CQ04 | Who holds a role on R34DA059723, and what role? | 2 | same | same | find the project by grant number; its people, with the role on each link |
| CQ05 | Which investigators hold roles on more than one project? | 7 | same | same | from each project, its people; count the projects per person |
| CQ06 | Which organization is each investigator affiliated with? | 165 | same | same | from each organization, the people one link away |
| CQ07 | Which investigators have an ORCID? | 112 | same | same | list the investigators; read each one's ORCID |
| CQ08 | Who are the members of WG-Devices? | 66 | same | same | find the working group by name; from it, the people one link away |
| CQ09 | Which projects study the house mouse? | 7 | same | same | find the species by its common name; from it, the projects one link away |
| CQ10 | Which projects study mammals? | 25 | same | same | find the mammal species; from each, its projects |
| CQ11 | Which projects name no resolvable species, and is that by design? | 4 | same | same | list the projects; keep those with no species named |
| CQ12 | Which publications came out of which project? | 89 | same | same | from each project, the publications one link away |
| CQ13 | Which datasets were produced under which project? | 5 | same | same | from each project, the datasets one link away |
| CQ14 | Which device categories does each project use? | 127 | same | same | from each project, the device categories one link away |
| CQ15 | Which devices does each manufacturer make, by category? | 35 | same | same | from each device, its maker and its category |
| CQ16 | Which software tools does the consortium provide, with their repositories? | 18 | same | same | list the software tools; read each one's repository |
| CQ17 | Which funding opportunities are still open (expiration after 2026-09-29)? | 10 | same | same | list the funding calls; keep those still open |
| CQ18 | Which jobs are posted, and by which institution? | 6 | same | same | list the jobs; from each, its organization's name, or the institution it names if it has none |
| CQ19 | Where did R34DA059723's title come from (source class and grade)? *(needs the full export)* | 0 | none | none | list the provenance records; keep the project's title; read the source's grade |
| CQ20 | Which investigators are on more than one project, and which projects? | 7 | same | same | from each project, its people; keep those on more than one |
| CQ21 | Which investigators have no ORCID recorded? | 134 | same | same | list the investigators; keep those with no ORCID |
| CQ22 | Which organization is each investigator tied to, directly or through a project? | 168 | same | same | from each person, their organization, and their projects' organizations |
| CQ23 | Who is in each working group, and on which projects are they? | 272 | same | same | from each working group, its members; from each member, their projects |
| CQ24 | Which investigators hold more than one kind of role? *(none in this export)* | 0 | none | none | from each project, its people and the role on each link |
| CQ25 | Which projects study the house mouse, whichever of its names is used? | 14 | same | same | find the species by any of its names; from it, its projects |
| CQ26 | How many projects study each species? | 13 | same | same | from each project, its species; count the projects per species |
| CQ27 | Which projects name a species in free text that is not resolved to a species node? *(none in this export)* | 0 | none | none | list the projects' species claims that no species node matches |
| CQ28 | How many publications, datasets, tools and models did each project produce? | 33 | same | same | from each project, count what it produced, by type |
| CQ29 | How many publications came out of each investigator's projects, and which projects? | 83 | same | same | from each project, its people and its publications |
| CQ30 | Which produced datasets have no provenance recorded? *(needs the full export)* | 0 | none | none | list the datasets; keep the produced ones no provenance record names |
| CQ31 | Which benchmarks is each ML model evaluated by, and which project produced it? *(none in this export)* | 0 | none | none | from each model, its benchmarks and the project that produced it |
| CQ32 | How many members does each organization have? | 59 | same | same | from each organization, count the members one link away |
| CQ33 | Which organizations have no members recorded? | 17 | same | same | list the organizations; keep those with no member |
| CQ34 | Which organizations have investigators on more than one project? | 10 | same | same | from each organization, its members; from each member, their projects |
| CQ35 | Which jobs does each institution advertise? | 4 | same | same | list the jobs; group them by organization, or by the institution named |
| CQ36 | Which kinds of role are being advertised? *(none in this export)* | 0 | none | none | list the jobs; count them by kind |
| CQ37 | Who posted each job? | 2 | same | same | list the jobs; from each, the person who posted it |
| CQ38 | Which projects have no outputs recorded? | 12 | same | same | list the projects; keep those that produced nothing |
| CQ39 | Which funding opportunities expire between 2026-10-14 and 2027-04-14? | 4 | same | same | list the funding calls; keep those expiring in the window |
| CQ40 | How many values come from a source graded below 3, by source and table? *(needs the full export)* | 0 | none | none | list the provenance records; read each source's grade |
| CQ41 | Which datasets did each grant fund, and who are its PIs? | 7 | same | same | from each project, the datasets it funded and its PIs |
| CQ42 | Which working groups have no member with a role on any project? *(none in this export)* | 0 | none | none | from each working group, its members; see whether any has a project |

All 42 are the questions the knowledge graph is scored on ([`kg/competency_questions.yaml`](kg/competency_questions.yaml)). A question of the form "which X has no Y" lists every X with no Y *recorded*, which in a graph still being linked is not the same as having none.

</details>

Times are over stdio on one machine (Linux x86_64, Python 3.10.20) and will differ on yours. Everything else is the same wherever it is run.
<!-- kg-mcp-benchmark:end -->

Regenerate this block with `uv run kg/bench_mcp_server.py --update README.md`.

## Tech Stack

- React 18 + TypeScript + Vite
Expand Down
4 changes: 3 additions & 1 deletion e2e/data.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,10 @@ test.describe("tables load with data", () => {

for (const table of CORE_TABLES) {
test(`table has rows: ${table}`, async ({ request }) => {
// select=id, not *: anon may read only the public columns of resources and announcements
// (20261117190000), and select=* asks for every column, so it is refused (401) there.
const res = await request.head(
`${SUPABASE_URL}/rest/v1/${table}?select=*&limit=1`,
`${SUPABASE_URL}/rest/v1/${table}?select=id&limit=1`,
{
headers: {
...AUTH_HEADERS,
Expand Down
Loading
Loading