Skip to content

Shared API for MCP and CLI tool subcommand #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
kalomak wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

Shared API for MCP and CLI tool subcommand #78

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4e164a8
rename server.py > api.py
kalomak May 20, 2026
4544d16
separate mcp definitions from api.py to mcp.py
kalomak May 20, 2026
402c8a1
add tool subcommand to give CLI access to all MCP commands
kalomak May 20, 2026
a7c14f6
cleaner import
kalomak May 20, 2026
68b2c02
rename test_server to test_api
kalomak May 20, 2026
d9795de
add tool subcommand to skill.md
kalomak May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,7 +327,7 @@ pip install paper-search-mcp
"mcpServers": {
"paper-search-mcp": {
"command": "python",
"args": ["-m", "paper_search_mcp.server"],
"args": ["-m", "paper_search_mcp.mcp"],
"env": {
"PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
"PAPER_SEARCH_MCP_CORE_API_KEY": "",
Expand Down Expand Up @@ -419,7 +419,7 @@ git clone https://github.com/openags/paper-search-mcp.git
cd paper-search-mcp

# 3. Verify it runs (uv auto-resolves dependencies, no manual install needed)
uv run -m paper_search_mcp.server
uv run -m paper_search_mcp.mcp
```

**Claude Desktop config** (replace the directory path with your actual clone location):
Expand All @@ -432,7 +432,7 @@ uv run -m paper_search_mcp.server
"args": [
"run",
"--directory", "/path/to/paper-search-mcp",
"-m", "paper_search_mcp.server"
"-m", "paper_search_mcp.mcp"
],
"env": {
"PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
Expand All @@ -451,7 +451,7 @@ uv run -m paper_search_mcp.server
For example, if you cloned to `/Users/mac/Pengsong/paper-search-mcp`:

```json
"args": ["run", "--directory", "/Users/mac/Pengsong/paper-search-mcp", "-m", "paper_search_mcp.server"]
"args": ["run", "--directory", "/Users/mac/Pengsong/paper-search-mcp", "-m", "paper_search_mcp.mcp"]
```

> `uv run` automatically installs dependencies into an isolated environment on first run — no `pip install` or `venv` needed.
Expand Down
18 changes: 18 additions & 0 deletions claude-code/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,24 @@ uv run --directory <REPO_PATH> paper-search read <source> <paper_id> [-o ./downl
uv run --directory <REPO_PATH> paper-search sources
```

### Tool

The `tool` subcommand exposes API functions. Use it when you need source-specific functions or parameters that the regular top-level CLI does not expose. Positional API arguments stay positional, and optional arguments become kebab-case flags.

```bash
# List all shared API functions exposed through the tool subcommand
uv run --directory <REPO_PATH> paper-search tool -h

# Inspect the arguments for one specific shared API function
uv run --directory <REPO_PATH> paper-search tool search_crossref -h

# Crossref-specific filters and sorting
uv run --directory <REPO_PATH> paper-search tool search_crossref "transformer attention" --filter from-pub-date:2024-01-01,has-full-text:true --sort published --order desc --max-results 2

# Direct DOI lookup
uv run --directory <REPO_PATH> paper-search tool get_crossref_paper_by_doi 10.1038/nature12373
```

## Output

`search` and `download` return JSON. `read` returns plain text. Config warnings go to stderr and can be ignored.
Expand Down
Loading