{
  "markdown": "# OokCite MCP Server\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Crates.io](https://img.shields.io/crates/v/ookcite-mcp.svg)](https://crates.io/crates/ookcite-mcp)\n[![npm](https://img.shields.io/npm/v/@turtletech/ookcite-mcp.svg)](https://www.npmjs.com/package/@turtletech/ookcite-mcp)\n\nGive MCP-capable tools the ability to validate DOIs, format citations, manage\nbibliography collections, and catch fabricated references. Returns citation\nmetadata only -- not PDFs or full-text articles. Works with clients that support\nMCP servers over standard input and output.\n\n## Quick Start\n\nOne command to install and configure:\n\n```bash\nnpx @turtletech/ookcite-mcp setup\n```\n\nThis auto-detects supported MCP clients and writes the configuration for you.\nConnect an OokCite account for higher rate limits and collection tools without\nputting an API key in shell arguments or MCP configuration:\n\n```bash\nnpx @turtletech/ookcite-mcp setup --connect\n```\n\nThe command opens the TurtleTech dashboard, creates or activates the Free plan,\nstores the issued key in the platform credential store, and writes only a\ncredential reference to detected clients. Use `setup --connect --device` on a\nheadless machine.\n\nAn existing API key remains supported:\n\n```bash\nnpx @turtletech/ookcite-mcp setup --key YOUR_API_KEY\n```\n\nNo API key required for basic usage (20 lookups/day).\n[Sign up](https://my.turtletech.us/signup?service=ookcite&source=ookcite_mcp) for more.\n\nAfter changing MCP config, restart the client or reload its MCP servers.\nMany clients do not hot-reload environment-variable changes for already-running\nstdio servers.\n\n## Install (Alternative Methods)\n\n**npm** (recommended):\n\n```bash\nnpm install -g @turtletech/ookcite-mcp\n```\n\n**cargo-binstall** (fastest, no Node.js):\n\n```bash\ncargo binstall ookcite-mcp\n```\n\n**cargo install** (from source):\n\n```bash\ncargo install ookcite-mcp\n```\n\n**Pre-built binaries**: Download from\n[GitHub Releases](https://github.com/TurtleTech-ehf/ookcite-mcp/releases)\nfor Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows.\n\n## Configure\n\nIf you used `setup`, you're done. Otherwise, add to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"ookcite\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@turtletech/ookcite-mcp\"]\n    }\n  }\n}\n```\n\nWith an API key:\n\n```json\n{\n  \"mcpServers\": {\n    \"ookcite\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@turtletech/ookcite-mcp\"],\n      \"env\": {\n        \"OOKCITE_API_KEY\": \"your_key_here\"\n      }\n    }\n  }\n}\n```\n\nIf you installed globally (`npm install -g` or `cargo install`), you can use\n`\"command\": \"ookcite-mcp\"` directly instead of npx.\n\n### Keeping the key out of the config file\n\n`setup --connect` uses the platform credential store by default. It refuses to\nreplace an existing platform credential or named OokCite MCP configuration\nunless `--replace-credential` or `--replace-config` is given explicitly.\n\nA generic credential manager can be used instead. The store command receives\nthe new key on standard input; it must not expect the key in a command-line\nargument. The retrieval command prints the key on standard output when the MCP\nserver starts:\n\n```bash\nnpx @turtletech/ookcite-mcp setup --connect \\\n  --store-command \"credential-cli store ookcite\" \\\n  --retrieve-command \"credential-cli read ookcite\"\n```\n\nFor an explicit owner-only file instead of a credential manager:\n\n```bash\nnpx @turtletech/ookcite-mcp setup --connect \\\n  --credential-file \"$HOME/.config/ookcite/api-key\"\n```\n\nThe file is created with owner-only permissions and is never overwritten. The\nplatform, helper-command, and file forms put references such as these in client\nconfiguration:\n\n```json\n{\n  \"mcpServers\": {\n    \"ookcite\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@turtletech/ookcite-mcp\"],\n      \"env\": {\n        \"OOKCITE_API_KEY_COMMAND\": \"credential-cli read ookcite\"\n      }\n    }\n  }\n}\n```\n\nAt startup, source precedence remains `OOKCITE_API_KEY`,\n`OOKCITE_API_KEY_COMMAND`, `OOKCITE_API_KEY_FILE`, then the platform credential\nreference. With none of them the server starts anonymous. `setup --key` remains\navailable for existing deployments that intentionally keep the key in client\nconfiguration.\n\nCredential retrieval obeys two constraints:\n\n- Retrieval receives closed standard input, so it cannot consume MCP JSON-RPC.\n- Retrieval is bounded by `OOKCITE_API_KEY_TIMEOUT`, which defaults to 10\n  seconds, and its output is never copied into diagnostics.\n\nConsult your client's MCP documentation for its configuration-file location.\nUse the `mcpServers.ookcite` JSON above when automatic setup is unavailable,\nthen restart the client or reload its MCP servers.\n\nOptional env (stdio MCP, all clients):\n\n| Variable | Purpose |\n| -------- | ------- |\n| `OOKCITE_API_KEY` | Higher rate limits + collection tools (optional for basic lookup/format) |\n| `OOKCITE_API` | Override API base URL (default `https://ookcite-api.turtletech.us`) |\n| `OOKCITE_MCP_READ_ONLY` | `1` hard-disables collection mutations (review / CI automation) |\n| `OOKCITE_MCP_ALLOW_MUTATE` | `0` denies mutations; unset or `1` allows (API key still required server-side) |\n| `OOKCITE_STARTUP_PROBES` | `1` runs auth + npm update checks on **stderr** before accepting MCP connections (default off for faster connect) |\n| `OOKCITE_API_KEY_COMMAND` | Command printing the key on stdout; stdin is closed |\n| `OOKCITE_API_KEY_FILE` | Owner-protected file whose first line is the key |\n| `OOKCITE_API_KEY_TIMEOUT` | Seconds allowed for credential retrieval (default 10) |\n| `OOKCITE_CREDENTIAL_STORE` | `platform` to load a platform credential reference |\n| `OOKCITE_CREDENTIAL_SERVICE` | Platform credential service name (default `ookcite-mcp`) |\n| `OOKCITE_CREDENTIAL_ACCOUNT` | Platform credential account name (default `default`) |\n\n### MCP usage tips\n\n- Prefer **batch** tools (`verify_references`, `batch_format`, `batch_add_to_collection`,\n  `import_bibliography`) over many single-citation calls.\n- Collection mutations require `OOKCITE_API_KEY`. Destructive tools\n  (`delete_collection`, `remove_from_collection`, `unshare_collection`) are\n  annotated for clients that honor MCP tool hints.\n- The server writes diagnostics to **stderr** only on the MCP path; stdout is\n  reserved for JSON-RPC.\n\n## Tools\n\n### Lookup & Validation\n\n| Tool                | Purpose                                       |\n| ------------------- | --------------------------------------------- |\n| `validate_doi`      | Check if a DOI exists (anti-hallucination)    |\n| `lookup_isbn`       | Look up a book by ISBN                        |\n| `reverse_lookup`    | Find a paper from messy citation text         |\n| `batch_resolve`     | Resolve many citation strings in one request (max 50) |\n| `enhanced_search`   | Corpus search with author / category / citation facets |\n| `health_check`      | Check API availability and health             |\n\n### Formatting\n\n| Tool                | Purpose                                       |\n| ------------------- | --------------------------------------------- |\n| `format_citation`   | Format a DOI in any of 2900+ CSL styles       |\n| `verify_references` | Batch-check a list of DOIs                    |\n| `batch_format`      | Format multiple citations at once             |\n| `search_styles`     | Find CSL style IDs by name                    |\n| `list_styles`       | Page through the full CSL style list          |\n| `group_cite`        | Generate grouped in-text markers (e.g. [1-3]) |\n\n### Account\n\n| Tool     | Purpose                                                  |\n| -------- | -------------------------------------------------------- |\n| `usage`  | Plan in effect plus daily (and monthly) lookups remaining |\n\n### ORCID\n\n| Tool             | Purpose                                                |\n| ---------------- | ------------------------------------------------------ |\n| `orcid_search`   | Find ORCID profiles by name, affiliation, or ORCID ID  |\n| `orcid_profile`  | Fetch one ORCID profile by ID                          |\n| `ingest_orcid`   | Index an ORCID profile's publications so they are searchable |\n\n### Collections (requires sign-in)\n\nCollections are a signed-in feature. Set `OOKCITE_API_KEY` to use these tools.\n\n| Tool                       | Purpose                                  |\n| -------------------------- | ---------------------------------------- |\n| `list_collections`         | List saved citation collections          |\n| `add_to_collection`        | Add a citation (by DOI or free-text)     |\n| `batch_add_to_collection`  | Add multiple citations at once           |\n| `import_bibliography`      | Import BibTeX/RIS files into a collection|\n| `export_collection`        | Export collection as BibTeX              |\n| `search_collection`        | Search within a collection; returns `entry_id` per match |\n| `check_duplicates`         | Check for duplicates; returns `entry_id` for matches     |\n| `delete_collection`        | Delete a collection                     |\n| `update_collection`        | Update name, description, or style      |\n| `remove_from_collection`   | Remove an entry by `entry_id`, bare DOI, or `doi:10.x/y` |\n| `update_entry_metadata`    | Correct a saved entry's title, authors, year, DOI, … |\n| `merge_entries`            | Merge two entries of one collection into one |\n| `update_tags`              | Set tags on a collection                |\n| `reorder_collection`       | Reorder entries                         |\n\nTypical workflow:\n\n1. Keep `references.bib` or `library.bib` under version control in your project\n2. Import that file into an OokCite collection with `import_bibliography`\n3. Use `search_collection`, `check_duplicates`, and `export_collection` while revising\n4. Treat the collection as an audit/export companion, not the only copy of your bibliography\n\n**Removing a single entry:** call `search_collection` (or `check_duplicates`) to\nsee each hit as `entry_id: …` (and optionally `aliases: doi:…` when the stored id\nis opaque). Pass that `entry_id` to `remove_from_collection`, or pass the paper's\nbare DOI / `doi:10.x/y` — the server resolves aliases locally before the API call.\n\n### Sharing & Collection Operations\n\n| Tool                  | Purpose                                    |\n| --------------------- | ------------------------------------------ |\n| `share_collection`    | Create a shareable link                    |\n| `unshare_collection`  | Revoke sharing                             |\n| `view_shared`         | View a shared collection by token          |\n| `merge_collections`   | Merge multiple collections                 |\n| `batch_move_entries`  | Move entries between collections           |\n\nSharing is available to signed-in accounts with collections.\nFree accounts can import and batch-add within their daily quota.\nMerge and batch-move require an Academic or Business plan.\n\n### Utilities\n\n| Tool                      | Purpose                                       |\n| ------------------------- | --------------------------------------------- |\n| `generate_citation_keys`  | Better BibTeX-style keys for a list of DOIs   |\n| `expand_journal`          | Expand a journal abbreviation to its full name |\n| `normalize_bibliography`  | Re-render BibTeX or RIS as canonical BibTeX   |\n\nThese three require an Academic or Business plan.\n\n## Plans & Pricing\n\n| Tier      | Price     | Lookups/day | API calls/month | Collections | Entries/collection |\n| --------- | --------- | ----------- | --------------- | ----------- | ------------------ |\n| Anonymous | Free      | 20          | --              | 0           | --                 |\n| Free      | Free      | 60          | --              | 4           | 200                |\n| Academic  | EUR 4/mo  | 20,000      | 10,000          | 10          | 1,000              |\n| Business  | EUR 10/mo | 20,000      | 40,000          | 20          | 4,000              |\n\nRe-lookups can be served without quota use when collection metadata is already\navailable to the API. A retrieval that has to resolve the paper again can count\nagainst the current plan's quota. Paid Academic checkout is intended for\nstudents, researchers, and educators at accredited institutions; a verified\nORCID can also qualify a signed-in account for Academic limits.\n\n## Anti-Hallucination\n\nAdd this to your system prompt:\n\n> Before citing any paper, use validate_doi to confirm the reference exists.\n> If validation fails, do not include the citation.\n\nFor revision workflows, add:\n\n> Keep the project bibliography in a local `.bib` file under version control.\n> Use OokCite collections for verification, deduplication, and export.\n\n## How It Works\n\nThe MCP server connects to the public [OokCite](https://ookcite.turtletech.us)\nAPI to look up and format citations. It's a thin MCP wrapper around the OokCite\nREST API with no local database, and no heavy dependencies.\n\n[Sign up](https://my.turtletech.us/signup?service=ookcite&source=ookcite_mcp) for a free account (60 lookups/day),\nor upgrade to Academic (EUR 4/mo) or Business (EUR 10/mo) for higher monthly\nAPI limits, larger collections, paid utilities, merge, and batch-move.\n\n\n## Source layout\n\nThe crate is a thin MCP (stdio) wrapper around the public OokCite REST API.\nThere is no local citation database; all state lives on the API.\n\n| Path | Role |\n|------|------|\n| `src/main.rs` | Binary entry: `--version`, `setup`, start MCP server |\n| `src/cli.rs` | Startup probes (validate `OOKCITE_API_KEY` via `/api/v1/me`, update check) |\n| `src/setup.rs` | `ookcite-mcp setup` / `npx add-mcp` client config installer |\n| `src/server.rs` | `Server` + `#[tool_router]` MCP tool handlers (plus unit tests at bottom) |\n| `src/tool_args.rs` | Tool argument structs (`serde` + `schemars`) |\n| `src/constants.rs` | API base URL, package version, reverse-lookup confidence threshold |\n| `src/http_error.rs` | `error_detail` and HTTP status classification for client-facing strings |\n| `src/collection_entries.rs` | Collection entry ids, bare DOI / `doi:` alias resolution, search lines |\n| `src/resolve_helpers.rs` | Reverse-lookup and free-text resolve payload helpers |\n| `src/endpoints.rs` | Endpoint registry (`lib` crate surface); contract-tested |\n| `src/lib.rs` | Library root (exports `endpoints` only) |\n| `tests/api_contract.rs` | Decrypts `contract/openapi.json.age`; asserts every endpoint exists |\n| `contract/` | Age-encrypted OpenAPI snapshot + `regen.sh` |\n| `npm/` | `@turtletech/ookcite-mcp` installer/wrapper (downloads release binary) |\n| `demo/` | Asciinema recording scripts |\n| `scripts/set-version.sh` | Cocogitto pre-bump hook: `Cargo.toml` + `npm/package.json` version |\n\n**Collections / entry ids:** `search_collection` and `check_duplicates` emit\n`entry_id: …` lines. `remove_from_collection` accepts that id, a bare DOI, or\n`doi:10.x/y` (resolved locally in `collection_entries` before the DELETE call).\n\n**Release:** tag `v*` runs `.github/workflows/release.yml` (multi-arch GitHub\nRelease assets, crates.io, npm). Version bumps use [cocogitto](https://docs.cocogitto.io/)\n(`cog.toml` + `scripts/set-version.sh`).\n\n**Why `server.rs` is large:** `rmcp`'s `#[tool_router]` / `#[tool]` macros keep\nhandlers on one `impl Server`. Further file splits without macro workarounds\nadd little user value; peel tests or add small helpers (`resolve_many`, shared\n`Me` type) before fighting the macro.\n\n## Contributing / local checks\n\n```bash\ncargo test --bin ookcite-mcp          # unit tests (no contract key needed)\ncargo build --release\n./target/release/ookcite-mcp --version\n\n# Contract tests (optional locally; required in CI with secret):\nexport OOKCITE_CONTRACT_KEY=\"value-from-your-credential-manager\"\ncargo test --test api_contract\n```\n\nLive MCP smoke (optional; needs `OOKCITE_API_KEY`): add/search/remove with a\nbare DOI on a throwaway collection, then `delete_collection`.\n\n## Documentation\n\n- [Full MCP setup guide](https://ookcite.turtletech.us/docs/howto/mcp-setup/)\n- [OokCite app](https://ookcite.turtletech.us/app)\n- [TurtleTech](https://turtletech.us)\n\n## License\n\nMIT. see [LICENSE](LICENSE).\n",
  "bytes": 16150,
  "sha": "cfc9392ad49826ae13c87a7053e14af02f08358064c154b50d97298a92e9c8ba",
  "repo_slug": "turtletech-ehf/ookcite-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_turtletech_ehf_ookcite_mcp_b7c8282e/readme"
}