admin/TWBG_Materials
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backup materials and knowledge-base docs

Browse Source
This commit is contained in:
admin
2026-05-30 16:22:29 +08:00
commit 93e50e8fce
3024 changed files with 2994945 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
文档润色流和知识库构建流/claude-scholar-upstream/MCP_SETUP.md Normal file
View File

@@ -0,0 +1,194 @@
# MCP Server Setup Guide
Claude Scholar relies on MCP (Model Context Protocol) servers for extended capabilities. MCP servers are **not included** in this repository — users must install and configure them separately.
## Required MCP Servers
### 1. Zotero MCP (Research Workflow)
**Used by**: `literature-reviewer` agent, `/research-init`, `/zotero-review`, `/zotero-notes` commands
**Package**: [Galaxy-Dawn/zotero-mcp](https://github.com/Galaxy-Dawn/zotero-mcp) — auto-detects local Zotero desktop vs Web API mode; Web credentials are only required for remote access or write tools.
#### Features
| Category | Tools |
|----------|-------|
| **Import** | `zotero_add_items_by_identifier`, `zotero_add_items_by_doi`, `zotero_add_items_by_arxiv`, `zotero_add_item_by_url` |
| **Read** | `zotero_get_collections`, `zotero_get_collection_items`, `zotero_search_items`, `zotero_semantic_search` |
| **Update** | `zotero_update_item`, `zotero_update_note`, `zotero_create_collection`, `zotero_move_items_to_collection`, `zotero_reconcile_collection_duplicates` |
| **Delete** | `zotero_delete_items` (to trash), `zotero_delete_collection` |
| **PDF** | `zotero_find_and_attach_pdfs` (source-aware PDF cascade), `zotero_add_linked_url_attachment` |
#### Prerequisites
1. Install [Zotero](https://www.zotero.org/) if you want local read-only access without Web API credentials
2. For write tools or remote Web API access, open [Zotero Settings -> Security -> Applications](https://www.zotero.org/settings/security#applications)
3. Click `Create new private key` to generate your API key
4. On the same page, copy the `User ID` shown below the button. Use this numeric value as `ZOTERO_LIBRARY_ID` for personal libraries
#### Installation
```bash
# Install via uv (recommended)
uv tool install git+https://github.com/Galaxy-Dawn/zotero-mcp.git
```
#### Configuration
Choose your platform below:
##### Claude Code
For Claude Code v2.1.5+, add to your `~/.claude.json` under `mcpServers`.
For earlier versions, add to your `~/.claude/settings.json` under `mcpServers`:
```json
{
"mcpServers": {
"zotero": {
"command": "zotero-mcp",
"args": ["serve"],
"env": {
"ZOTERO_API_KEY": "your-api-key",
"ZOTERO_LIBRARY_ID": "your-user-id",
"ZOTERO_LIBRARY_TYPE": "user",
"UNPAYWALL_EMAIL": "your-email@example.com",
"UNSAFE_OPERATIONS": "all"
}
}
}
}
```
##### Codex CLI
Add to your `~/.codex/config.toml`:
```toml
[mcp_servers.zotero]
command = "zotero-mcp"
args = ["serve"]
enabled = true
[mcp_servers.zotero.env]
ZOTERO_API_KEY = "your-api-key"
ZOTERO_LIBRARY_ID = "your-user-id"
ZOTERO_LIBRARY_TYPE = "user"
UNPAYWALL_EMAIL = "your-email@example.com"
UNSAFE_OPERATIONS = "all"
NO_PROXY = "localhost,127.0.0.1"
```
##### OpenCode
Add to your `~/.opencode/opencode.jsonc`:
```jsonc
{
"mcp": {
"zotero": {
"type": "local",
"command": ["zotero-mcp", "serve"],
"enabled": true
}
}
}
```
Then set environment variables in `~/.zshrc`:
```bash
# Zotero MCP
export ZOTERO_API_KEY="your-api-key"
export ZOTERO_LIBRARY_ID="your-user-id"
export ZOTERO_LIBRARY_TYPE="user"
export UNPAYWALL_EMAIL="your-email@example.com"
export UNSAFE_OPERATIONS="all"
```
#### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `ZOTERO_API_KEY` | No for local read-only; Yes for Web/write tools | Your Zotero API key |
| `ZOTERO_LIBRARY_ID` | No for local read-only; Yes for Web/write tools | Your Zotero `User ID` (numeric) for personal libraries |
| `ZOTERO_LIBRARY_TYPE` | Yes | `user` or `group` |
| `UNPAYWALL_EMAIL` | No | Email for Unpaywall PDF search |
| `UNSAFE_OPERATIONS` | No | `items` (delete_items), `all` (delete_collection) |
| `NO_PROXY` | No | Bypass proxy for localhost |
Notes:
- The minimal local setup is just `command = "zotero-mcp"` plus `args = ["serve"]`.
- Do not leave placeholder values such as `your-api-key`, `your-user-id`, or `your-email@example.com` in your live config.
#### Available Tools
| Tool | Purpose |
|------|---------|
| `zotero_get_collections` | List all collections |
| `zotero_get_collection_items` | Get items in a collection |
| `zotero_search_items` | Search library by keyword |
| `zotero_search_by_tag` | Search by tag |
| `zotero_get_item_metadata` | Get item metadata and abstract |
| `zotero_get_item_fulltext` | Read PDF full text |
| `zotero_get_annotations` | Get PDF annotations |
| `zotero_get_notes` | Get notes |
| `zotero_semantic_search` | Semantic search (uses embeddings) |
| `zotero_advanced_search` | Advanced search |
| `zotero_add_items_by_identifier` | Smart paper import from DOI, arXiv, landing pages, or direct PDF URLs; when web upload hits storage quota and Zotero Desktop is running, it can fall back to a local connector copy (`pdf_source=local_zotero_copy`) or reuse an existing local copy (`pdf_source=local_zotero_existing_copy`), exposing `local_item_key=...` when available |
| `zotero_add_items_by_doi` | Import papers by DOI |
| `zotero_add_items_by_arxiv` | Import preprints by arXiv ID |
| `zotero_add_item_by_url` | Save webpage as item |
| `zotero_update_item` | Update item fields |
| `zotero_update_note` | Update note content |
| `zotero_create_collection` | Create collection |
| `zotero_move_items_to_collection` | Move items between collections |
| `zotero_update_collection` | Rename collection |
| `zotero_delete_collection` | Delete collection |
| `zotero_delete_items` | Move items to trash |
| `zotero_find_and_attach_pdfs` | Re-run the source-aware PDF cascade for existing items |
| `zotero_reconcile_collection_duplicates` | Post-import dedupe and collection-level cleanup |
| `zotero_add_linked_url_attachment` | Add linked URL attachment |
Workflow note: Claude Scholar's current research startup path prefers `zotero_add_items_by_identifier` for import, then `zotero_reconcile_collection_duplicates` as the standard post-import cleanup. Import ledger and local-copy reconcile remain internal diagnostics rather than default public MCP tools.
### 2. Browser Automation MCP (Optional)
Used for: Chrome browser control, web page interaction.
#### Configuration
```json
{
"mcpServers": {
"streamable-mcp-server": {
"type": "streamable-http",
"url": "http://127.0.0.1:12306/mcp"
}
}
}
```
## Verification
After configuration, restart your CLI and verify MCP servers are connected:
```
# Zotero example:
> List my Zotero collections
```
If the tool responds with your data (for example collections), the setup is complete.
## Troubleshooting
| Issue | Solution |
|-------|----------|
| Tools return error | Check API key and library ID are correct |
| PDF attach fails | Ensure `UNPAYWALL_EMAIL` is set |
| Delete operations blocked | Set `UNSAFE_OPERATIONS=items` or `all` |
| HTTP errors | Check `NO_PROXY` includes localhost |
| API rate limit (429) | Batch ≤10 papers at a time, add delays between batches |