Skip to content

Commit f4d035c

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
feat(cartridges): add academic-workflow-mcp Zotero cartridge
Academic workflow cartridge with six MCP tools: - search_zotero: Search papers/collections in Zotero library - get_paper_metadata: Fetch title/authors/DOI/year/abstract - generate_citation: Export BibTeX/CSL-JSON/RIS/EndNote formats - extract_bibkeys: Parse text for citation keys - export_collection: Batch export collections as BibTeX - add_review_note: Annotate papers (typo/unclear/question/suggestion) Architecture (~270 LOC): - abi/AcademicWorkflow.idr: Idris2 proof-indexed citation formats - ffi/academic_ffi.zig: Zotero API + citation generation - adapter/mod.ts: Deno MCP server (127.0.0.1:5174) Type safety: Proof-indexed citation format support. Loopback invariant: IsLoopback 5174. Integrates with: Zotero Web API, CSL, BibTeX export. Highest external-facing ROI for academic teams. CRG Phase 3b: New-cartridge backlog item. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
1 parent df42793 commit f4d035c

9 files changed

Lines changed: 696 additions & 0 deletions

File tree

‎cartridges/academic-workflow-mcp/.editorconfig‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
root = true
2+
[*]
3+
charset = utf-8
4+
end_of_line = lf
5+
indent_size = 2
6+
indent_style = space
7+
insert_final_newline = true
8+
trim_trailing_whitespace = true

‎cartridges/academic-workflow-mcp/.gitignore‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
zig-cache/
2+
*.o
3+
*.a
4+
*.so
5+
*.dylib
6+
*.wasm
7+
deno.lock
8+
.deno/
9+
.vscode/
10+
.idea/
11+
*.swp
12+
.DS_Store
13+
node_modules/

‎cartridges/academic-workflow-mcp/LICENSE‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Mozilla Public License Version 2.0
2+
3+
This academic-workflow-mcp cartridge is licensed under the Mozilla Public
4+
License, Version 2.0 as the legal fallback. The preferred license is
5+
PMPL-1.0-or-later.
6+
7+
See SPDX-License-Identifier headers in source files.
8+
For MPL-2.0 text: https://opensource.org/licenses/MPL-2.0

‎cartridges/academic-workflow-mcp/README.adoc‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
= Academic Workflow Cartridge
2+
:toc: preamble
3+
:author: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
:date: 2026-04-25
5+
:spdx: PMPL-1.0-or-later
6+
7+
// SPDX-License-Identifier: PMPL-1.0-or-later
8+
9+
Zotero integration for academic research workflows — search papers, manage citations, add review notes.
10+
11+
== Features
12+
13+
- **Zotero Search** — Query papers and collections
14+
- **Metadata Extraction** — Fetch full paper metadata (title, authors, DOI, year, abstract)
15+
- **Citation Export** — Generate citations in BibTeX, CSL-JSON, RIS, EndNote formats
16+
- **Review Annotations** — Add notes to papers (typo, unclear, question, suggestion)
17+
- **Batch Export** — Export entire collections as BibTeX
18+
19+
== Architecture
20+
21+
[cols="1,3"]
22+
|===
23+
| Component | Purpose
24+
25+
| `abi/AcademicWorkflow.idr`
26+
| Idris2 interface with proof-indexed citation formats.
27+
28+
| `ffi/academic_ffi.zig`
29+
| Zig bindings for Zotero API calls and citation generation.
30+
31+
| `adapter/mod.ts`
32+
| Deno MCP server bridging Zotero API and citation tools.
33+
Runs on `127.0.0.1:5174` (loopback only).
34+
35+
| `cartridge.json`
36+
| Tool manifest with 6 MCP tools for academic workflow.
37+
|===
38+
39+
== MCP Tools
40+
41+
=== `search_zotero`
42+
Search Zotero library (supports filtering by collection).
43+
44+
=== `get_paper_metadata`
45+
Fetch complete metadata for a paper by Zotero item ID.
46+
47+
=== `generate_citation`
48+
Export paper citation in requested format (BibTeX/CSL/RIS/EndNote).
49+
50+
=== `extract_bibkeys`
51+
Parse text and extract citation keys (\cite{...}, @key patterns).
52+
53+
=== `export_collection`
54+
Export entire Zotero collection as BibTeX file.
55+
56+
=== `add_review_note`
57+
Add review annotation (page, text, category) to a paper.
58+
59+
== Integration
60+
61+
Connects to Zotero via:
62+
- **Zotero Web API** (https://www.zotero.org/support/dev/web_api) for library access
63+
- **Citation Style Language** (CSL) for format generation
64+
- **BibTeX export** for LaTeX workflows
65+
66+
Loopback proof pinning: `IsLoopback 5174` at compile-time.
67+
68+
== CRG Phase 3b: New-cartridge backlog
69+
70+
High external-facing ROI for academic teams (citations, paper management).
71+
Matches gossamer-mcp template (~270 LOC ABI+FFI+adapter).
72+
73+
== License
74+
75+
PMPL-1.0-or-later (MPL-2.0 legal fallback).

‎cartridges/academic-workflow-mcp/abi/AcademicWorkflow.idr‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
-- SPDX-License-Identifier: PMPL-1.0-or-later
2+
-- Academic Workflow Cartridge ABI — Citations, Zotero, paper review
3+
4+
module AcademicWorkflow
5+
6+
||| Paper metadata
7+
public record Paper where
8+
constructor MkPaper
9+
title : String
10+
authors : List String
11+
doi : String
12+
year : Nat
13+
abstract : String
14+
15+
||| Citation format
16+
public data CitationFormat =
17+
| BibTeX
18+
| CSL
19+
| RIS
20+
| EndNote
21+
22+
||| Proof that a citation format is supported
23+
public data Supported : CitationFormat -> Type where
24+
SupportedBibTeX : Supported BibTeX
25+
SupportedCSL : Supported CSL
26+
SupportedRIS : Supported RIS
27+
SupportedEndNote : Supported EndNote
28+
29+
||| Review annotation
30+
public record ReviewNote where
31+
constructor MkReviewNote
32+
page : Nat
33+
text : String
34+
category : String -- "typo", "unclear", "question", "suggestion"
35+
36+
||| Zotero collection reference
37+
public record ZoteroCollection where
38+
constructor MkZoteroCollection
39+
id : String
40+
name : String
41+
itemCount : Nat
42+
43+
||| Academic workflow operations
44+
public interface AcademicWorkflow.Workflow (m : Type -> Type) where
45+
||| Search Zotero collections
46+
searchZotero : (query : String) -> m (List ZoteroCollection)
47+
48+
||| Fetch paper metadata from Zotero
49+
getPaperMetadata : (itemId : String) -> m Paper
50+
51+
||| Generate citation in requested format
52+
generateCitation : {fmt : CitationFormat} ->
53+
(paper : Paper) ->
54+
Supported fmt -> m String
55+
56+
||| Extract BibTeX keys from text
57+
extractBibKeys : (text : String) -> m (List String)
58+
59+
||| Add review annotations to paper
60+
addReviewNote : (paperId : String) -> (note : ReviewNote) -> m ()
61+
62+
||| Export collection as BibTeX
63+
exportCollection : (collectionId : String) -> m String
64+
65+
||| Loopback proof: academic-mcp runs on 127.0.0.1:5174
66+
public data IsLoopback : (port : Nat) -> Type where
67+
LoopbackProof : IsLoopback 5174
68+
69+
export
70+
loopbackInvariant : IsLoopback 5174
71+
loopbackInvariant = LoopbackProof

0 commit comments

Comments
 (0)