# miscite — LLM / AI Agent Guide

> Scholar research workspace: semantic literature search, citation analysis,
> research profile, library, alerts, and recommendations.

## What miscite does

miscite is a citation-check and research workspace platform for academics.
It analyzes PDF/DOCX manuscripts to flag citation issues (missing references,
retractions, predatory venues, inappropriate citations), provides semantic
literature search over OpenAlex-indexed academic works, and offers a full
research workspace with library management, research profiles, and
automated research alerts with LLM-planned search strategies.

## Connecting via MCP (recommended)

miscite exposes all services through a Model Context Protocol (MCP) server
using Streamable HTTP transport.

MCP endpoint: https://miscite.review/mcp/

### Claude Code

Add miscite to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "miscite": {
      "type": "http",
      "url": "https://miscite.review/mcp/"
    }
  }
}
```

Or run: `claude mcp add miscite --transport http https://miscite.review/mcp/`

### Claude Desktop

Claude Desktop requires the `mcp-remote` bridge for remote HTTP servers.
Add to your config file
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
`%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "miscite": {
      "command": "npx",
      "args": ["mcp-remote", "https://miscite.review/mcp/"]
    }
  }
}
```

### OpenAI Codex

Add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project):

```toml
[mcp_servers.miscite]
url = "https://miscite.review/mcp/"
```

### Other MCP clients

Any MCP-compatible client can connect using:

- **URL:** `https://miscite.review/mcp/`
- **Transport:** Streamable HTTP

### Authentication

All tools except `health` and `ready` require an API Bearer token passed as
the `token` parameter. Tokens are created from the account settings page at
/account or via the `create_api_token` tool.

## Available MCP tools (42 total)

### Search (3 tools)

`search` — Search academic literature. POST /api/v1/search/query
  - token (str, required): API Bearer token
  - query (str, required): search query text
  - limit (int, default 20): max results, 1-100
  - retrieval_mode (str, default "hybrid"): "semantic", "lexical", or "hybrid"
  - sort_by (str, default "relevance"): "relevance" or "cited_by_count"
  - filters (dict, optional): {publication_year_min, publication_year_max,
    wos_indexes, languages, open_access, ...}
  Returns: list of works with title, authors, DOI, OpenAlex ID, abstract,
  citation counts, WoS metrics, source/journal info, and relevance scores.

`search_health` — Check search service availability. GET /api/v1/search/health
  - token (str, required): API Bearer token
  Returns: status, active collection name, Qdrant mode.

`work_lookup` — Look up a work by OpenAlex ID. GET /api/v1/search/works/{id}
  - token (str, required): API Bearer token
  - openalex_id (str, required): e.g. "W2100837269"
  - include_fulltext (bool, default false): include fulltext markdown
  Returns: full work metadata, optionally with fulltext content.

### Analysis (7 tools)

`upload_document` — Upload PDF/DOCX for citation analysis. POST /api/v1/analysis/upload
  - token (str, required): API Bearer token
  - filename (str, required): original filename, must end in .pdf or .docx
  - file_content_base64 (str, required): base64-encoded file content
  - content_type (str, default "application/pdf"): MIME type
  Returns: job ID and initial status. The analysis runs asynchronously
  (typically 1-5 minutes). Poll with `get_job` until status is "completed".

`list_jobs` — List analysis jobs. GET /api/v1/analysis/jobs
  - token (str, required): API Bearer token
  - status (str, optional): filter by "processing", "completed", or "failed"
  - limit (int, default 25): max results, 1-100
  - offset (int, default 0): pagination offset
  Returns: list of jobs with id, status, filename, created/updated timestamps.

`get_job` — Get job status and report. GET /api/v1/analysis/jobs/{job_id}
  - token (str, required): API Bearer token
  - job_id (str, required): the job ID
  Returns: job status. When completed, includes full report with:
  - summary: total citations, resolved/unresolved counts, issues found
  - citations[]: each citation with match status, confidence, candidates
  - issues[]: retractions, predatory venues, missing refs, inappropriate citations
  - deep_analysis (if enabled): ranked recommendations, reviewer candidates

`cancel_job` — Cancel a running job. POST /api/v1/analysis/jobs/{job_id}/cancel
  - token (str, required): API Bearer token
  - job_id (str, required): the job ID

`delete_job` — Delete job and document. DELETE /api/v1/analysis/jobs/{job_id}
  - token (str, required): API Bearer token
  - job_id (str, required): the job ID

`get_report_pdf` — Download report as PDF. GET /api/v1/analysis/jobs/{job_id}/report.pdf
  - token (str, required): API Bearer token
  - job_id (str, required): the job ID
  Returns: base64-encoded PDF content.

`share_report` — Share report via email. POST /api/v1/analysis/jobs/{job_id}/share-email
  - token (str, required): API Bearer token
  - job_id (str, required): job ID of a completed report
  - recipient_email (str, required): email address to share with
  - personal_message (str, default ""): optional message, max 500 chars

### Library (12 tools)

Manage a Zotero-style collection tree of saved references. Collections can
be nested using path-style names (e.g. "Research/ML Papers"). System
collections (Unfiled, Own publications) cannot be deleted.
Items can have file attachments (PDFs, etc.).

`list_collections` — List all collections. GET /api/v1/sync/collections
  - token (str, required): API Bearer token
  Returns: list of collections with id, name, description, item count.

`create_collection` — Create a collection. POST /api/v1/sync/collections
  - token (str, required): API Bearer token
  - name (str, required): collection name, max 120 chars
  - description (str, default ""): optional description

`delete_collection` — Delete a collection. DELETE /api/v1/sync/collections/{id}
  - token (str, required): API Bearer token
  - collection_id (int, required): collection ID

`list_items` — List library items. GET /api/v1/sync/items
  - token (str, required): API Bearer token
  - limit (int, default 100): max results, 1-500
  - offset (int, default 0): pagination offset
  - since (str, optional): ISO datetime for incremental sync
  Returns: list of items with title, authors, DOI, source, year, notes, etc.

`create_item` — Create a library item. POST /api/v1/sync/items
  - token (str, required): API Bearer token
  - title (str, required): title of the work
  - doi (str, default ""): DOI identifier
  - openalex_id (str, default ""): OpenAlex ID
  - authors (list[dict], optional): [{"name": "..."}, ...]
  - source_display_name (str, default ""): journal/source name
  - publication_year (int, optional): year of publication
  - work_type (str, default ""): e.g. "journal-article"
  - notes (str, default ""): user notes
  - collection_ids (list[int], optional): collections to add the item to

`update_item` — Update item metadata. PUT /api/v1/sync/items/{item_id}
  - token (str, required): API Bearer token
  - item_id (int, required): item ID
  - updates (dict, required): fields to update (title, doi, authors, notes, etc.)

`delete_item` — Delete a library item. DELETE /api/v1/sync/items/{item_id}
  - token (str, required): API Bearer token
  - item_id (int, required): item ID

`save_search_hit` — Save a search result to library. POST /api/v1/sync/items
  - token (str, required): API Bearer token
  - title (str, required): title of the work
  - openalex_id (str, default ""): OpenAlex ID from search results
  - doi (str, default ""): DOI from search results
  - collection_id (int, optional): collection to save into
  - payload (dict, optional): full work metadata payload from search results

`list_item_files` — List files attached to a library item. GET /api/v1/sync/items/{item_id}/files
  - token (str, required): API Bearer token
  - item_id (int, required): library item ID
  Returns: list of files with id, filename, content_type, file_size, sha256, created_at.

`download_file` — Download a library file as base64. GET /api/v1/sync/files/{file_id}/download
  - token (str, required): API Bearer token
  - file_id (int, required): file ID
  Returns: base64-encoded file content.

`upload_item_file` — Upload a file attachment to a library item. POST /api/v1/sync/items/{item_id}/files
  - token (str, required): API Bearer token
  - item_id (int, required): library item ID
  - filename (str, required): original filename (e.g. "paper.pdf")
  - file_content_base64 (str, required): base64-encoded file content
  - content_type (str, default "application/pdf"): MIME type

`delete_file` — Delete a file attachment. DELETE /api/v1/sync/files/{file_id}
  - token (str, required): API Bearer token
  - file_id (int, required): file ID

### Profile (5 tools)

Research identity with LLM-summarized fields, interest tags (pinned + auto),
and connected public profiles.

`get_profile` — Get research profile. GET /api/v1/profile/
  - token (str, required): API Bearer token
  Returns: profile fields, interest tags, connected sources, refresh status.

`update_interests` — Update interest tags. PATCH /api/v1/profile/interests
  - token (str, required): API Bearer token
  - tags (list, required): list of tag strings or dicts with "label" and
    optional "pinned" (bool) keys. Example: ["machine learning",
    {"label": "NLP", "pinned": true}]

`refresh_profile` — Trigger profile refresh. POST /api/v1/profile/refresh
  - token (str, required): API Bearer token
  Triggers async re-import from connected sources and LLM re-summarization.

`list_sources` — List connected sources. GET /api/v1/profile/sources
  - token (str, required): API Bearer token
  Returns: sources by type (google_scholar, orcid, academia, homepage)
  with URL, fetch status, and extracted metadata.

`sync_sources` — Connect/update profile sources. POST /api/v1/profile/sources/sync
  - token (str, required): API Bearer token
  - urls_by_type (dict, required): {"google_scholar": "https://scholar...",
    "orcid": "https://orcid.org/0000-...", "homepage": "https://faculty..."}

### Alerts (8 tools)

Research alerts with LLM-planned multi-query searches, three-section digests
(Latest Research, Most Relevant, Classics), engagement-aware query planning,
and post-search LLM refinement.

`list_alerts` — List all alerts. GET /api/v1/alerts/
  - token (str, required): API Bearer token
  Returns: list of alerts with config, schedule, and last digest info.

`save_alert` — Create or update an alert. POST /api/v1/alerts/
  - token (str, required): API Bearer token
  - title (str, required): alert title
  - enabled (bool, default true): whether alert is active
  - include_profile (bool, default true): use profile interests in search
  - custom_query_text (str, default ""): custom search query
  - search_method (str, default "semantic"): "semantic", "lexical", or "hybrid"
  - frequency (str, default "weekly"): "daily", "weekly", "biweekly", "monthly"
  - library_item_ids (list[int], optional): library items as search context
  - wos_only (bool, default false): restrict to WoS-indexed works
  - wos_indexes (list[str], optional): e.g. ["SCIE", "SSCI"]
  - wos_quartiles (list[str], optional): e.g. ["Q1", "Q2"]
  - wos_jci_quartiles (list[str], optional): JCI quartile filters
  - day_of_week (int, optional): 0=Monday to 6=Sunday (for weekly)
  - day_of_month (int, optional): 1-28 (for monthly)
  - alert_id (int, optional): if set, updates existing alert

`preview_alert` — Preview alert results without saving. POST /api/v1/alerts/preview
  - token (str, required): API Bearer token
  - (same config params as save_alert, minus alert_id)

`toggle_alert` — Enable/disable an alert. PATCH /api/v1/alerts/{alert_id}/toggle
  - token (str, required): API Bearer token
  - alert_id (int, required): alert ID
  - enabled (bool, required): true to enable, false to disable

`delete_alert` — Delete an alert. DELETE /api/v1/alerts/{alert_id}
  - token (str, required): API Bearer token
  - alert_id (int, required): alert ID

`send_digest` — Generate and send digest now. POST /api/v1/alerts/{alert_id}/digest
  - token (str, required): API Bearer token
  - alert_id (int, required): alert ID

`run_research_updates` — Generate fresh recommendations. POST /api/v1/alerts/research-updates
  - token (str, required): API Bearer token
  Generates profile-based research update recommendations using
  engagement-aware LLM query planning and post-search refinement.

`save_research_update` — Save recommendation to library. POST /api/v1/alerts/research-updates/save
  - token (str, required): API Bearer token
  - hit_payload (dict, required): full search hit payload (must include
    openalex_id and/or title)
  - collection_id (int, optional): collection to save into

### Account (4 tools)

`get_me` — Get current user info. GET /api/v1/sync/me
  - token (str, required): API Bearer token

`list_api_tokens` — List API tokens. GET /api/v1/sync/tokens
  - token (str, required): API Bearer token

`create_api_token` — Create new API token. POST /api/v1/sync/tokens
  - token (str, required): API Bearer token
  - label (str, default "API Token"): label for the token
  Returns the raw token value (shown only once — save it).

`revoke_api_token` — Revoke an API token. DELETE /api/v1/sync/tokens/{token_id}
  - token (str, required): API Bearer token
  - token_id (int, required): token ID to revoke

### System (3 tools)

`health` — Liveness probe. GET /healthz (no auth required)

`ready` — Readiness probe. GET /readyz (no auth required)

`feedback` — Submit user feedback. POST /api/feedback
  - token (str, required): API Bearer token
  - message (str, required): feedback text
  - page (str, default ""): page context
  - category (str, default ""): feedback category

## REST API (alternative)

All MCP tools map 1:1 to JSON REST endpoints. Authenticate with
`Authorization: Bearer <token>` header. Key prefixes:

- POST /api/v1/search/query — search (body: query, limit, retrieval_mode, sort_by, filters)
- GET  /api/v1/search/works/{openalex_id} — work lookup (?include_fulltext=true)
- POST /api/v1/analysis/upload — multipart file upload
- GET  /api/v1/analysis/jobs — list jobs (?status=&limit=&offset=)
- GET  /api/v1/analysis/jobs/{id} — job status + report
- POST /api/v1/analysis/jobs/{id}/cancel — cancel
- DELETE /api/v1/analysis/jobs/{id} — delete
- GET  /api/v1/analysis/jobs/{id}/report.pdf — PDF download
- POST /api/v1/analysis/jobs/{id}/share-email — email share
- GET  /api/v1/profile/ — profile
- PATCH /api/v1/profile/interests — update interest tags
- POST /api/v1/profile/refresh — trigger refresh
- GET  /api/v1/profile/sources — list sources
- POST /api/v1/profile/sources/sync — connect sources
- GET  /api/v1/alerts/ — list alerts
- POST /api/v1/alerts/ — create/update alert
- POST /api/v1/alerts/preview — preview alert
- PATCH /api/v1/alerts/{id}/toggle — toggle alert
- DELETE /api/v1/alerts/{id} — delete alert
- POST /api/v1/alerts/{id}/digest — send digest
- POST /api/v1/alerts/research-updates — generate recommendations
- POST /api/v1/alerts/research-updates/save — save recommendation
- GET  /api/v1/sync/me — current user
- GET  /api/v1/sync/collections — list collections
- POST /api/v1/sync/collections — create collection
- DELETE /api/v1/sync/collections/{id} — delete collection
- GET  /api/v1/sync/items — list items (?limit=&offset=&since=)
- POST /api/v1/sync/items — create item
- PUT  /api/v1/sync/items/{id} — update item
- DELETE /api/v1/sync/items/{id} — delete item
- GET  /api/v1/sync/items/{id}/files — list item files
- POST /api/v1/sync/items/{id}/files — upload file (multipart)
- GET  /api/v1/sync/files/{id}/download — download file
- DELETE /api/v1/sync/files/{id} — delete file
- GET  /api/v1/sync/tokens — list API tokens
- POST /api/v1/sync/tokens — create API token (?label=)
- DELETE /api/v1/sync/tokens/{id} — revoke API token
- GET  /api/v1/search-history/ — list search history
- DELETE /api/v1/search-history/{id} — delete history entry

## Common workflows

### 1. Literature search and save
1. `search` with your query and filters
2. Review results (title, abstract, citation count, WoS metrics)
3. `work_lookup` with include_fulltext=true for promising results
4. `save_search_hit` to add to a library collection

### 2. Citation analysis
1. `upload_document` with base64 file content
2. Poll `get_job` until status is "completed" (typically 1-5 minutes)
3. Read report: check issues[] for retractions, predatory venues, missing refs
4. `get_report_pdf` for a formatted report
5. `share_report` to email results to collaborators

### 3. Research profile setup
1. `sync_sources` with Google Scholar / ORCID / homepage URLs
2. `refresh_profile` to import and summarize
3. `update_interests` to pin important tags
4. `run_research_updates` to get personalized recommendations

### 4. Research alerts
1. `save_alert` with search config and schedule
2. `preview_alert` to check results before committing
3. Digests auto-generate on schedule, or `send_digest` on demand
4. `save_research_update` to save interesting finds to library

## Error responses

On error, tools return {"error": "description", "status_code": 4xx/5xx}.
Common codes: 401 (invalid/missing token), 403 (forbidden), 404 (not found),
422 (validation error), 429 (rate limited).