Skip to content

feat(tools): add external tool registration API - #113

Open
Yyu-ang wants to merge 1 commit into
cookjohn:mainfrom
Yyu-ang:upstream-direct/pr92-external-tool-api-rebase-20260913
Open

Yyu-ang wants to merge 1 commit into
cookjohn:mainfrom
Yyu-ang:upstream-direct/pr92-external-tool-api-rebase-20260913

Conversation

@Yyu-ang

@Yyu-ang Yyu-ang commented Sep 13, 2026

Copy link
Copy Markdown

This is the external-tool API split requested during the review of #92.

What this PR adds

A public API that allows other Zotero plugins to register custom MCP tools through:

Zotero.ZoteroMCP.api

The API exposes:

  • registerTool(def): boolean
  • unregisterTool(name): boolean
  • unregisterAllTools(pluginID): number
  • getRegisteredTools()
  • isToolRegistered(name)
  • onToolListChanged(callback)

Tool registration

External tool definitions support:

  • tool name
  • description
  • JSON input schema
  • async or synchronous handler
  • optional pluginID
  • optional enabled state

Registered tools are exposed through the existing MCP tools/list and dispatched through the existing MCP server.

Safety and compatibility

  • external tool names must match the registry naming rules
  • duplicate registrations are rejected
  • built-in MCP tool names cannot be overridden
  • export_bibliography, get_citation, and list_citation_styles are reserved
  • the planned sync_bib and cite names are also reserved
  • pluginID remains optional
  • no separate enable/disable preference or registration-handle API is introduced

This keeps the public API compatible with the implementation discussed in #92.

Lifecycle

The registry is process-wide and survives MCP server restarts. Third-party plugins can unregister individual tools or clean up all tools associated with their pluginID during shutdown.

The PR also includes:

  • TypeScript API typings
  • an external-plugin example
  • English and Chinese documentation
  • registry regression tests

Scope

This PR contains only the external tool registration API.

It does not include:

  • citation/export implementation
  • sync_bib / cite
  • semantic search dialog
  • version or release metadata

Validation

  • rebased onto the current main
  • full npm test passes
  • production npm run build passes
  • registry tests cover registration, removal, optional pluginID, duplicate/reserved names, and sync_bib / cite reservation

Related: #92

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant