{"id":20600012,"url":"https://github.com/mungell/zotserver","last_synced_at":"2025-07-16T16:36:33.614Z","repository":{"id":65980930,"uuid":"454576374","full_name":"MunGell/ZotServer","owner":"MunGell","description":"Zotero Local HTTP Server","archived":false,"fork":false,"pushed_at":"2022-07-11T10:58:39.000Z","size":59,"stargazers_count":95,"open_issues_count":1,"forks_count":10,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-15T00:41:37.803Z","etag":null,"topics":["zotero","zotero-addon","zotero-api","zotero-plugin","zotserver"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MunGell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-01T22:48:06.000Z","updated_at":"2025-04-10T09:46:38.000Z","dependencies_parsed_at":"2023-02-19T19:31:11.137Z","dependency_job_id":null,"html_url":"https://github.com/MunGell/ZotServer","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/MunGell/ZotServer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MunGell%2FZotServer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MunGell%2FZotServer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MunGell%2FZotServer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MunGell%2FZotServer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MunGell","download_url":"https://codeload.github.com/MunGell/ZotServer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MunGell%2FZotServer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265524824,"owners_count":23782043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["zotero","zotero-addon","zotero-api","zotero-plugin","zotserver"],"created_at":"2024-11-16T08:34:48.475Z","updated_at":"2025-07-16T16:36:33.555Z","avatar_url":"https://github.com/MunGell.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZotServer for Zotero\n\nZotServer provides locally accessible HTTP API.\nThis is a convenient way to integrate Zotero with other desktop applications that require access to its database.\n\nMy motivation for development of this addon is to connect my note-taking software to Zotero database without active internet connection.\nI am working on a [connector](https://github.com/MunGell/obsidian-zotero) that will allow me to quickly search and link to Zotero items right from the text editor.\n\n## Installation\n\n1. Download lastest stable version of the addon from [GitHub release page of this repository](https://github.com/MunGell/ZotServer/releases/)\n2. Use \"Install addon from file\" menu link in Zotero and select the downloaded `.xpi` file\n\n\u003e How to find \"Install addon from file\" option:\n\u003e 1. Go to \"Tools\" menu, click on \"Add-ons\" option\n\u003e 2. Click on a cog icon on top right corner\n\u003e 3. There now should be \"Install Add-on From File\" option\n\n## Alternatives\n\nZotero already provides a couple of ways to access its database:\n\n1. [Direct access to SQLite database](https://www.zotero.org/support/dev/client_coding/direct_sqlite_database_access)\n2. [Web API of Zotero Storage service](https://www.zotero.org/support/dev/web_api/v3/start)\n3. [zotero-api-endpoint](https://github.com/Dominic-DallOsto/zotero-api-endpoint) plugin team is working on the similar functionality\n\nZotServer addon provides a third way with local-only HTTP API that uses [JavaSceript API](https://www.zotero.org/support/dev/client_coding/javascript_api) internally.\n\n## Implementation\n\nZotero is already coming with an [HTTP server implementation](https://github.com/zotero/zotero/blob/master/chrome/content/zotero/xpcom/server.js) that runs on port `23119`.\nIt serves [browser connector endpoints](https://github.com/zotero/zotero/blob/master/chrome/content/zotero/xpcom/connector/server_connector.js) to add new items to Zotero database.\n\nZotServer relies on the original implementation of the server and augments it with new endpoints to serve functionality like [database search](https://github.com/MunGell/ZotServer/blob/main/src/endpoints/Search.ts)\n\n## Endpoint Security\n\nPlease see [discussion](https://github.com/MunGell/ZotServer/issues/1) for more information.\n\n## Documentation\n\n### Search\n\n`POST /zotserver/search`\n\nA search endpoint that expects POST request with JSON body that describes [search conditions](https://www.zotero.org/support/dev/client_coding/javascript_api#zotero_search_basics).\n\nExample JSON body:\n\n```json\n[\n    {\n        \"condition\": \"quicksearch-everything\",\n        \"value\": \"Ahrens\"\n    },\n    {\n        \"condition\": \"tag\",\n        \"operator\": \"is\",\n        \"value\": \"productivity\"\n        \"required\": true\n    }\n]\n```\n\nJSON body contains an array of search conditions.\nEach search condition can have following fields:\n\n|Field      |Required|Defaults To|\n|-----------|--------|-----------|\n|`condition`| Yes    | None      |\n|`operator` | No     |`contains` |\n|`value`    | Yes    | None      |\n|`required` | No     |`false`    |\n\nFollowing conditions are accepted:\n\n| Condition                      | Description                                                          | Default Operator   |\n|--------------------------------|----------------------------------------------------------------------|--------------------|\n| `quicksearch-everything`       | Search on all item fields, similar to search field in Zotero UI      | `contains`         |\n| `quicksearch-titleCreatorYear` | Search on title, creator and year fields                             | `contains`         |\n| `tag`                          | Search on a particular tag                                           | None               |\n\nSome more conditions are described here: [Zotero JavaScript API on search](https://www.zotero.org/support/dev/client_coding/javascript_api#zotero_search_basics)\n\n## Roadmap\n\nCurrent roadmap is basically based on the idea of parity with [functionality](https://www.zotero.org/support/dev/web_api/v3/basics) of [Zotero Storage](https://www.zotero.org/storage).\n\n## Contributing\n\nZotServer is written with [TypeScript](https://www.typescriptlang.org) and main source code is located under `src` directory.\n\nI am assuming that the majority of contributions will be dealing with existing or new endpoints. Below is an overview of endpoints structure.\n\nAll endpoint code should be placed in `src/endpoints` directory in a file named after the class it contains.\n\nA simple template for such file is below:\n\n```js\nimport EndpointInterface from '../types/EndpointInterface';\n\nexport default class Collections implements EndpointInterface {\n    supportedMethods = ['GET','POST','PUT','DELETE'];\n    supportedDataTypes = ['application/json'];\n    permitBookmarklet = false;\n\n    public async init(request: any) {\n        return [200, 'application/json', JSON.stringify('response data')];\n    }\n}\n```\n\n`init` is the main method that should return a response array in specified format: `[\u003chttp response code\u003e, \u003cresponse content type\u003e, \u003cresponse body\u003e]`.\n\nExample `request` object (for search endpoint in this particular case):\n\n```json\n{\n    \"method\": \"POST\",\n    \"pathname\": \"/zotserver/search\",\n    \"query\": {},\n    \"headers\": {\n        \"Content-Type\": \"application/json\",\n        \"User-Agent\": \"browser\",\n        \"Accept\": \"*/*\",\n        \"Cache-Control\": \"no-cache\",\n        \"Host\": \"localhost:23119\",\n        \"Accept-Encoding\": \"gzip, deflate, br\",\n        \"Connection\": \"keep-alive\",\n        \"Content-Length\": \"89\"\n    },\n    \"data\": [\n        { \"condition\": \"quicksearch-everything\", \"value\": \"Ahrens\"}\n    ]\n}\n```\n\nYou will then need to register this new endpoint in `zotserver.ts` file and assing it unique url path.\n\nEndpoints implementation relies on [Zotero JavaScript API](https://www.zotero.org/support/dev/client_coding/javascript_api).\n\nFor more information on addon development workflow please refer to [Zotero Plugin Development](https://www.zotero.org/support/dev/client_coding/plugin_development) page.\n\nHere is my command to run Zotero in development mode that you might find useful:\n\n```sh\n/Applications/Zotero.app/Contents/MacOS/zotero -p \u003cyour-development-profile-name\u003e -ZoteroDebugText -jsconsole -purgecache\n```\n\nFor questions or help requests please join Gitter room: https://gitter.im/ZotServer/community\n\nYour contributions are highly appreciated!\n\n## License\n\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmungell%2Fzotserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmungell%2Fzotserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmungell%2Fzotserver/lists"}