semantic-scholar-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- semantic_scholar_mcp-0.1.0/.claude/settings.json +43 -0
- semantic_scholar_mcp-0.1.0/.env.example +28 -0
- semantic_scholar_mcp-0.1.0/.github/dependabot.yml +43 -0
- semantic_scholar_mcp-0.1.0/.github/workflows/release.yml +56 -0
- semantic_scholar_mcp-0.1.0/.github/workflows/test-pypi.yml +56 -0
- semantic_scholar_mcp-0.1.0/.gitignore +160 -0
- semantic_scholar_mcp-0.1.0/ARCHITECTURE.md +309 -0
- semantic_scholar_mcp-0.1.0/CLAUDE.md +202 -0
- semantic_scholar_mcp-0.1.0/LICENSE +21 -0
- semantic_scholar_mcp-0.1.0/PKG-INFO +215 -0
- semantic_scholar_mcp-0.1.0/README.md +172 -0
- semantic_scholar_mcp-0.1.0/docs/ARCHITECTURE.md +715 -0
- semantic_scholar_mcp-0.1.0/docs/DEVELOPER_GUIDE.md +1200 -0
- semantic_scholar_mcp-0.1.0/docs/USER_GUIDE.md +823 -0
- semantic_scholar_mcp-0.1.0/docs/api-specification.yaml +733 -0
- semantic_scholar_mcp-0.1.0/docs/uml/01-overview-class-diagram.puml +326 -0
- semantic_scholar_mcp-0.1.0/docs/uml/01-overview-class-diagram.svg +1 -0
- semantic_scholar_mcp-0.1.0/docs/uml/02-overview-component-diagram.puml +108 -0
- semantic_scholar_mcp-0.1.0/docs/uml/02-overview-component-diagram.svg +1 -0
- semantic_scholar_mcp-0.1.0/docs/uml/03-overview-deployment-diagram.puml +88 -0
- semantic_scholar_mcp-0.1.0/docs/uml/03-overview-deployment-diagram.svg +1 -0
- semantic_scholar_mcp-0.1.0/docs/uml/04-flow-paper-search-sequence.puml +126 -0
- semantic_scholar_mcp-0.1.0/docs/uml/04-flow-paper-search-sequence.svg +1 -0
- semantic_scholar_mcp-0.1.0/docs/uml/05-flow-paper-retrieval-activity.puml +113 -0
- semantic_scholar_mcp-0.1.0/docs/uml/05-flow-paper-retrieval-activity.svg +1 -0
- semantic_scholar_mcp-0.1.0/docs/uml/06-pattern-circuit-breaker-state.puml +57 -0
- semantic_scholar_mcp-0.1.0/docs/uml/06-pattern-circuit-breaker-state.svg +1 -0
- semantic_scholar_mcp-0.1.0/docs/uml/README.md +145 -0
- semantic_scholar_mcp-0.1.0/pyproject.toml +168 -0
- semantic_scholar_mcp-0.1.0/server_standalone.py +14 -0
- semantic_scholar_mcp-0.1.0/src/__init__.py +15 -0
- semantic_scholar_mcp-0.1.0/src/core/__init__.py +58 -0
- semantic_scholar_mcp-0.1.0/src/core/abstractions.py +371 -0
- semantic_scholar_mcp-0.1.0/src/core/cache.py +98 -0
- semantic_scholar_mcp-0.1.0/src/core/config.py +293 -0
- semantic_scholar_mcp-0.1.0/src/core/container.py +363 -0
- semantic_scholar_mcp-0.1.0/src/core/exceptions.py +489 -0
- semantic_scholar_mcp-0.1.0/src/core/logging.py +358 -0
- semantic_scholar_mcp-0.1.0/src/core/metrics.py +572 -0
- semantic_scholar_mcp-0.1.0/src/core/missing_types.py +36 -0
- semantic_scholar_mcp-0.1.0/src/core/protocols.py +257 -0
- semantic_scholar_mcp-0.1.0/src/core/types.py +130 -0
- semantic_scholar_mcp-0.1.0/src/main.py +399 -0
- semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/__init__.py +7 -0
- semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/__main__.py +6 -0
- semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/api_client.py +259 -0
- semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/api_client_enhanced.py +713 -0
- semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/base_models.py +122 -0
- semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/domain_models.py +253 -0
- semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/models.py +51 -0
- semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/models_enhanced.py +851 -0
- semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/server.py +774 -0
- semantic_scholar_mcp-0.1.0/test_api_direct.py +125 -0
- semantic_scholar_mcp-0.1.0/test_basic.py +62 -0
- semantic_scholar_mcp-0.1.0/test_mcp_tools.py +91 -0
- semantic_scholar_mcp-0.1.0/test_readme_functions.py +204 -0
- semantic_scholar_mcp-0.1.0/test_search.py +101 -0
- semantic_scholar_mcp-0.1.0/test_simple_search.py +96 -0
- semantic_scholar_mcp-0.1.0/tests/conftest.py +59 -0
- semantic_scholar_mcp-0.1.0/tests/test_http_integration.py.disabled +183 -0
- semantic_scholar_mcp-0.1.0/tests/test_integration_mcp.py +300 -0
- semantic_scholar_mcp-0.1.0/tests/test_models.py +256 -0
- semantic_scholar_mcp-0.1.0/tests/test_real_api.py.disabled +121 -0
- semantic_scholar_mcp-0.1.0/tests/test_server_logic.py +131 -0
- semantic_scholar_mcp-0.1.0/uml_diagrams.puml +1427 -0
- semantic_scholar_mcp-0.1.0/uv.lock +1866 -0
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
{
|
|
2
|
+
"hooks": {
|
|
3
|
+
"before_file_edit": "echo '๐ Editing: {{file_path}}'",
|
|
4
|
+
"after_file_edit": "echo 'โ
Edit completed: {{file_path}}'",
|
|
5
|
+
|
|
6
|
+
"before_file_write": "echo '๐ Creating: {{file_path}}'",
|
|
7
|
+
"after_file_write": "echo 'โ
Created: {{file_path}}'",
|
|
8
|
+
|
|
9
|
+
"before_bash": "echo '๐ Running: {{command}}'",
|
|
10
|
+
"after_bash": "echo 'โ
Command completed'",
|
|
11
|
+
|
|
12
|
+
"after_edit_python": "cd /mnt/ext-hdd1/yoshioka/github/semantic-scholar-mcp && uv run ruff check {{file_path}} --fix",
|
|
13
|
+
|
|
14
|
+
"before_test": "echo '๐งช Starting tests...'",
|
|
15
|
+
"after_test": "echo 'โ
Tests completed'",
|
|
16
|
+
|
|
17
|
+
"before_git_commit": "cd /mnt/ext-hdd1/yoshioka/github/semantic-scholar-mcp && uv run ruff check . --fix",
|
|
18
|
+
|
|
19
|
+
"after_pyproject_edit": "cd /mnt/ext-hdd1/yoshioka/github/semantic-scholar-mcp && uv sync"
|
|
20
|
+
},
|
|
21
|
+
|
|
22
|
+
"project": {
|
|
23
|
+
"name": "Semantic Scholar MCP",
|
|
24
|
+
"type": "python-mcp",
|
|
25
|
+
"root": "/mnt/ext-hdd1/yoshioka/github/semantic-scholar-mcp",
|
|
26
|
+
"python_version": "3.10",
|
|
27
|
+
"package_manager": "uv"
|
|
28
|
+
},
|
|
29
|
+
|
|
30
|
+
"development": {
|
|
31
|
+
"auto_format": true,
|
|
32
|
+
"lint_on_save": true,
|
|
33
|
+
"test_command": "uv run pytest",
|
|
34
|
+
"build_command": "uv build",
|
|
35
|
+
"run_command": "uv run python -m semantic_scholar_mcp"
|
|
36
|
+
},
|
|
37
|
+
|
|
38
|
+
"mcp": {
|
|
39
|
+
"server_file": "server_standalone.py",
|
|
40
|
+
"inspector_command": "uv run mcp dev server_standalone.py",
|
|
41
|
+
"test_file": "test_simple_search.py"
|
|
42
|
+
}
|
|
43
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Environment configuration
|
|
2
|
+
ENVIRONMENT=development
|
|
3
|
+
|
|
4
|
+
# Semantic Scholar API (optional - works without key but with lower rate limits)
|
|
5
|
+
SEMANTIC_SCHOLAR_API_KEY=
|
|
6
|
+
|
|
7
|
+
# Logging
|
|
8
|
+
LOG_LEVEL=INFO
|
|
9
|
+
LOG_FORMAT=json
|
|
10
|
+
|
|
11
|
+
# Cache settings
|
|
12
|
+
CACHE__ENABLED=true
|
|
13
|
+
CACHE__TTL_SECONDS=3600
|
|
14
|
+
CACHE__BACKEND=memory
|
|
15
|
+
|
|
16
|
+
# Rate limiting
|
|
17
|
+
RATE_LIMIT__ENABLED=true
|
|
18
|
+
RATE_LIMIT__REQUESTS_PER_SECOND=1.0
|
|
19
|
+
RATE_LIMIT__BURST_SIZE=10
|
|
20
|
+
|
|
21
|
+
# Circuit breaker
|
|
22
|
+
CIRCUIT_BREAKER__ENABLED=true
|
|
23
|
+
CIRCUIT_BREAKER__FAILURE_THRESHOLD=5
|
|
24
|
+
CIRCUIT_BREAKER__RECOVERY_TIMEOUT=60.0
|
|
25
|
+
|
|
26
|
+
# Metrics
|
|
27
|
+
METRICS__ENABLED=true
|
|
28
|
+
METRICS__BACKEND=memory
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
version: 2
|
|
2
|
+
updates:
|
|
3
|
+
# Python dependencies
|
|
4
|
+
- package-ecosystem: "pip"
|
|
5
|
+
directory: "/"
|
|
6
|
+
schedule:
|
|
7
|
+
interval: "weekly"
|
|
8
|
+
day: "monday"
|
|
9
|
+
time: "09:00"
|
|
10
|
+
open-pull-requests-limit: 10
|
|
11
|
+
reviewers:
|
|
12
|
+
- "hy20191108"
|
|
13
|
+
labels:
|
|
14
|
+
- "dependencies"
|
|
15
|
+
- "python"
|
|
16
|
+
commit-message:
|
|
17
|
+
prefix: "chore"
|
|
18
|
+
include: "scope"
|
|
19
|
+
groups:
|
|
20
|
+
development-dependencies:
|
|
21
|
+
patterns:
|
|
22
|
+
- "pytest*"
|
|
23
|
+
- "black"
|
|
24
|
+
- "ruff"
|
|
25
|
+
- "mypy"
|
|
26
|
+
- "coverage*"
|
|
27
|
+
|
|
28
|
+
# GitHub Actions
|
|
29
|
+
- package-ecosystem: "github-actions"
|
|
30
|
+
directory: "/"
|
|
31
|
+
schedule:
|
|
32
|
+
interval: "weekly"
|
|
33
|
+
day: "monday"
|
|
34
|
+
time: "09:00"
|
|
35
|
+
open-pull-requests-limit: 5
|
|
36
|
+
reviewers:
|
|
37
|
+
- "hy20191108"
|
|
38
|
+
labels:
|
|
39
|
+
- "dependencies"
|
|
40
|
+
- "github-actions"
|
|
41
|
+
commit-message:
|
|
42
|
+
prefix: "ci"
|
|
43
|
+
include: "scope"
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
name: PyPI Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
env:
|
|
9
|
+
PYTHON_VERSION: "3.10"
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
build-and-publish:
|
|
13
|
+
name: Build and Publish to PyPI
|
|
14
|
+
runs-on: ubuntu-latest
|
|
15
|
+
permissions:
|
|
16
|
+
id-token: write
|
|
17
|
+
steps:
|
|
18
|
+
- uses: actions/checkout@v4
|
|
19
|
+
|
|
20
|
+
- name: Install uv
|
|
21
|
+
uses: astral-sh/setup-uv@v6
|
|
22
|
+
|
|
23
|
+
- name: Set up Python
|
|
24
|
+
uses: actions/setup-python@v5
|
|
25
|
+
with:
|
|
26
|
+
python-version: ${{ env.PYTHON_VERSION }}
|
|
27
|
+
|
|
28
|
+
- name: Install dependencies
|
|
29
|
+
run: |
|
|
30
|
+
uv sync
|
|
31
|
+
|
|
32
|
+
- name: Run tests
|
|
33
|
+
run: |
|
|
34
|
+
uv run pytest tests/ -v
|
|
35
|
+
continue-on-error: true
|
|
36
|
+
|
|
37
|
+
- name: Run linting
|
|
38
|
+
run: |
|
|
39
|
+
uv run ruff check .
|
|
40
|
+
continue-on-error: true
|
|
41
|
+
|
|
42
|
+
- name: Build package
|
|
43
|
+
run: |
|
|
44
|
+
uv build
|
|
45
|
+
|
|
46
|
+
- name: Upload artifacts
|
|
47
|
+
uses: actions/upload-artifact@v4
|
|
48
|
+
with:
|
|
49
|
+
name: dist
|
|
50
|
+
path: dist/
|
|
51
|
+
|
|
52
|
+
- name: Publish to PyPI
|
|
53
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
54
|
+
with:
|
|
55
|
+
verbose: true
|
|
56
|
+
print-hash: true
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
name: Test PyPI Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [ "**" ] # All branches
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [ "**" ] # All pull requests
|
|
8
|
+
workflow_dispatch: # Manual trigger
|
|
9
|
+
|
|
10
|
+
env:
|
|
11
|
+
PYTHON_VERSION: "3.10"
|
|
12
|
+
|
|
13
|
+
jobs:
|
|
14
|
+
build-and-publish:
|
|
15
|
+
name: Build and Publish to Test PyPI
|
|
16
|
+
runs-on: ubuntu-latest
|
|
17
|
+
permissions:
|
|
18
|
+
id-token: write
|
|
19
|
+
steps:
|
|
20
|
+
- uses: actions/checkout@v4
|
|
21
|
+
|
|
22
|
+
- name: Install uv
|
|
23
|
+
uses: astral-sh/setup-uv@v6
|
|
24
|
+
|
|
25
|
+
- name: Set up Python
|
|
26
|
+
uses: actions/setup-python@v5
|
|
27
|
+
with:
|
|
28
|
+
python-version: ${{ env.PYTHON_VERSION }}
|
|
29
|
+
|
|
30
|
+
- name: Install dependencies
|
|
31
|
+
run: |
|
|
32
|
+
uv sync
|
|
33
|
+
|
|
34
|
+
- name: Run linting
|
|
35
|
+
run: |
|
|
36
|
+
uv run ruff check .
|
|
37
|
+
continue-on-error: true
|
|
38
|
+
|
|
39
|
+
- name: Build package
|
|
40
|
+
run: |
|
|
41
|
+
uv build
|
|
42
|
+
|
|
43
|
+
- name: Upload artifacts
|
|
44
|
+
uses: actions/upload-artifact@v4
|
|
45
|
+
with:
|
|
46
|
+
name: dist
|
|
47
|
+
path: dist/
|
|
48
|
+
|
|
49
|
+
- name: Publish to Test PyPI
|
|
50
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
51
|
+
if: github.event_name != 'pull_request' # Skip publishing for PRs
|
|
52
|
+
with:
|
|
53
|
+
repository-url: https://test.pypi.org/legacy/
|
|
54
|
+
verbose: true
|
|
55
|
+
print-hash: true
|
|
56
|
+
skip-existing: true
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# C extensions
|
|
7
|
+
*.so
|
|
8
|
+
|
|
9
|
+
# Distribution / packaging
|
|
10
|
+
.Python
|
|
11
|
+
build/
|
|
12
|
+
develop-eggs/
|
|
13
|
+
dist/
|
|
14
|
+
downloads/
|
|
15
|
+
eggs/
|
|
16
|
+
.eggs/
|
|
17
|
+
lib/
|
|
18
|
+
lib64/
|
|
19
|
+
parts/
|
|
20
|
+
sdist/
|
|
21
|
+
var/
|
|
22
|
+
wheels/
|
|
23
|
+
share/python-wheels/
|
|
24
|
+
*.egg-info/
|
|
25
|
+
.installed.cfg
|
|
26
|
+
*.egg
|
|
27
|
+
MANIFEST
|
|
28
|
+
|
|
29
|
+
# PyInstaller
|
|
30
|
+
*.manifest
|
|
31
|
+
*.spec
|
|
32
|
+
|
|
33
|
+
# Installer logs
|
|
34
|
+
pip-log.txt
|
|
35
|
+
pip-delete-this-directory.txt
|
|
36
|
+
|
|
37
|
+
# Unit test / coverage reports
|
|
38
|
+
htmlcov/
|
|
39
|
+
.tox/
|
|
40
|
+
.nox/
|
|
41
|
+
.coverage
|
|
42
|
+
.coverage.*
|
|
43
|
+
.cache
|
|
44
|
+
nosetests.xml
|
|
45
|
+
coverage.xml
|
|
46
|
+
*.cover
|
|
47
|
+
*.py,cover
|
|
48
|
+
.hypothesis/
|
|
49
|
+
.pytest_cache/
|
|
50
|
+
cover/
|
|
51
|
+
|
|
52
|
+
# Translations
|
|
53
|
+
*.mo
|
|
54
|
+
*.pot
|
|
55
|
+
|
|
56
|
+
# Django stuff:
|
|
57
|
+
*.log
|
|
58
|
+
local_settings.py
|
|
59
|
+
db.sqlite3
|
|
60
|
+
db.sqlite3-journal
|
|
61
|
+
|
|
62
|
+
# Flask stuff:
|
|
63
|
+
instance/
|
|
64
|
+
.webassets-cache
|
|
65
|
+
|
|
66
|
+
# Scrapy stuff:
|
|
67
|
+
.scrapy
|
|
68
|
+
|
|
69
|
+
# Sphinx documentation
|
|
70
|
+
docs/_build/
|
|
71
|
+
|
|
72
|
+
# PyBuilder
|
|
73
|
+
.pybuilder/
|
|
74
|
+
target/
|
|
75
|
+
|
|
76
|
+
# Jupyter Notebook
|
|
77
|
+
.ipynb_checkpoints
|
|
78
|
+
|
|
79
|
+
# IPython
|
|
80
|
+
profile_default/
|
|
81
|
+
ipython_config.py
|
|
82
|
+
|
|
83
|
+
# pyenv
|
|
84
|
+
.python-version
|
|
85
|
+
|
|
86
|
+
# pipenv
|
|
87
|
+
Pipfile.lock
|
|
88
|
+
|
|
89
|
+
# poetry
|
|
90
|
+
poetry.lock
|
|
91
|
+
|
|
92
|
+
# pdm
|
|
93
|
+
.pdm.toml
|
|
94
|
+
.pdm-python
|
|
95
|
+
|
|
96
|
+
# PEP 582
|
|
97
|
+
__pypackages__/
|
|
98
|
+
|
|
99
|
+
# Celery stuff
|
|
100
|
+
celerybeat-schedule
|
|
101
|
+
celerybeat.pid
|
|
102
|
+
|
|
103
|
+
# SageMath parsed files
|
|
104
|
+
*.sage.py
|
|
105
|
+
|
|
106
|
+
# Environments
|
|
107
|
+
.env
|
|
108
|
+
.venv
|
|
109
|
+
env/
|
|
110
|
+
venv/
|
|
111
|
+
ENV/
|
|
112
|
+
env.bak/
|
|
113
|
+
venv.bak/
|
|
114
|
+
|
|
115
|
+
# Spyder project settings
|
|
116
|
+
.spyderproject
|
|
117
|
+
.spyproject
|
|
118
|
+
|
|
119
|
+
# Rope project settings
|
|
120
|
+
.ropeproject
|
|
121
|
+
|
|
122
|
+
# mkdocs documentation
|
|
123
|
+
/site
|
|
124
|
+
|
|
125
|
+
# mypy
|
|
126
|
+
.mypy_cache/
|
|
127
|
+
.dmypy.json
|
|
128
|
+
dmypy.json
|
|
129
|
+
|
|
130
|
+
# Pyre type checker
|
|
131
|
+
.pyre/
|
|
132
|
+
|
|
133
|
+
# pytype static type analyzer
|
|
134
|
+
.pytype/
|
|
135
|
+
|
|
136
|
+
# Cython debug symbols
|
|
137
|
+
cython_debug/
|
|
138
|
+
|
|
139
|
+
# PyCharm
|
|
140
|
+
.idea/
|
|
141
|
+
|
|
142
|
+
# VS Code
|
|
143
|
+
.vscode/
|
|
144
|
+
|
|
145
|
+
# macOS
|
|
146
|
+
.DS_Store
|
|
147
|
+
|
|
148
|
+
# Windows
|
|
149
|
+
Thumbs.db
|
|
150
|
+
ehthumbs.db
|
|
151
|
+
|
|
152
|
+
# MCP specific
|
|
153
|
+
.mcp/
|
|
154
|
+
mcp-logs/
|
|
155
|
+
|
|
156
|
+
# Project specific
|
|
157
|
+
*.db
|
|
158
|
+
*.sqlite
|
|
159
|
+
logs/
|
|
160
|
+
cache/
|
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
# Semantic Scholar MCP Server Architecture
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
The Semantic Scholar MCP Server is an enterprise-grade implementation following clean architecture principles, with a strong focus on resilience, maintainability, and performance.
|
|
6
|
+
|
|
7
|
+
## Architecture Principles
|
|
8
|
+
|
|
9
|
+
### 1. Clean Architecture
|
|
10
|
+
- **Dependency Rule**: Dependencies point inward - outer layers depend on inner layers
|
|
11
|
+
- **Core Layer**: Contains business entities and rules with no external dependencies
|
|
12
|
+
- **Use Cases**: Application-specific business logic isolated from frameworks
|
|
13
|
+
- **Interface Adapters**: Convert data between use cases and external systems
|
|
14
|
+
- **Frameworks & Drivers**: External tools and frameworks at the outermost layer
|
|
15
|
+
|
|
16
|
+
### 2. SOLID Principles
|
|
17
|
+
- **Single Responsibility**: Each class has one reason to change
|
|
18
|
+
- **Open/Closed**: Open for extension, closed for modification
|
|
19
|
+
- **Liskov Substitution**: Implementations are interchangeable through interfaces
|
|
20
|
+
- **Interface Segregation**: Small, focused interfaces (protocols)
|
|
21
|
+
- **Dependency Inversion**: Depend on abstractions, not concretions
|
|
22
|
+
|
|
23
|
+
### 3. Domain-Driven Design
|
|
24
|
+
- **Domain Models**: Rich models representing Semantic Scholar entities
|
|
25
|
+
- **Value Objects**: Immutable objects like PaperId, AuthorId
|
|
26
|
+
- **Aggregates**: Paper as aggregate root with Citations and References
|
|
27
|
+
- **Repository Pattern**: Abstract data access through interfaces
|
|
28
|
+
|
|
29
|
+
## Layer Architecture
|
|
30
|
+
|
|
31
|
+
### Core Layer (`src/core/`)
|
|
32
|
+
The innermost layer containing:
|
|
33
|
+
- **Protocols**: Interface definitions using Python Protocol
|
|
34
|
+
- **Exceptions**: Domain-specific exception hierarchy
|
|
35
|
+
- **Types**: Type aliases and domain primitives
|
|
36
|
+
- **Base Models**: Abstract base classes for entities
|
|
37
|
+
|
|
38
|
+
No external dependencies allowed in this layer.
|
|
39
|
+
|
|
40
|
+
### Domain Layer (`src/semantic_scholar_mcp/`)
|
|
41
|
+
Business logic and domain models:
|
|
42
|
+
- **Domain Models**: Paper, Author, Citation, Reference
|
|
43
|
+
- **Business Rules**: Validation logic, invariants
|
|
44
|
+
- **Value Objects**: SearchQuery, SearchFilters
|
|
45
|
+
- **Domain Services**: Search operations, recommendations
|
|
46
|
+
|
|
47
|
+
### Application Layer
|
|
48
|
+
Use case implementations:
|
|
49
|
+
- **API Client**: SemanticScholarClient with business operations
|
|
50
|
+
- **MCP Server**: Tool, Resource, and Prompt handlers
|
|
51
|
+
- **Orchestration**: Coordinating multiple domain operations
|
|
52
|
+
|
|
53
|
+
### Infrastructure Layer
|
|
54
|
+
External concerns and implementations:
|
|
55
|
+
- **HTTP Client**: httpx integration
|
|
56
|
+
- **Caching**: In-memory cache implementation
|
|
57
|
+
- **Logging**: Structured logging with correlation IDs
|
|
58
|
+
- **Configuration**: Environment-based configuration
|
|
59
|
+
|
|
60
|
+
## Design Patterns
|
|
61
|
+
|
|
62
|
+
### 1. Repository Pattern
|
|
63
|
+
```python
|
|
64
|
+
class IRepository(Protocol):
|
|
65
|
+
async def get(self, id: str) -> Optional[Entity]: ...
|
|
66
|
+
async def save(self, entity: Entity) -> None: ...
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### 2. Factory Pattern
|
|
70
|
+
```python
|
|
71
|
+
class LoggerFactory:
|
|
72
|
+
def get_logger(self, name: str) -> ILogger:
|
|
73
|
+
# Create configured logger instance
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### 3. Strategy Pattern
|
|
77
|
+
```python
|
|
78
|
+
class ExponentialBackoffRetryStrategy:
|
|
79
|
+
def get_delay(self, attempt: int) -> float:
|
|
80
|
+
# Calculate retry delay
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### 4. Decorator Pattern
|
|
84
|
+
```python
|
|
85
|
+
@log_performance()
|
|
86
|
+
async def search_papers(...):
|
|
87
|
+
# Automatic performance logging
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### 5. Circuit Breaker Pattern
|
|
91
|
+
Prevents cascading failures:
|
|
92
|
+
- **Closed**: Normal operation, tracking failures
|
|
93
|
+
- **Open**: Fast fail, no downstream calls
|
|
94
|
+
- **Half-Open**: Testing recovery with limited requests
|
|
95
|
+
|
|
96
|
+
### 6. Observer Pattern
|
|
97
|
+
Context managers for correlation tracking:
|
|
98
|
+
```python
|
|
99
|
+
async with RequestContext(correlation_id=correlation_id):
|
|
100
|
+
# All logs include correlation ID
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Resilience Patterns
|
|
104
|
+
|
|
105
|
+
### 1. Circuit Breaker
|
|
106
|
+
- Failure threshold: 5 failures
|
|
107
|
+
- Recovery timeout: 60 seconds
|
|
108
|
+
- Half-open trials: 3 successful requests
|
|
109
|
+
|
|
110
|
+
### 2. Rate Limiting
|
|
111
|
+
- Token bucket algorithm
|
|
112
|
+
- Configurable rate and burst
|
|
113
|
+
- Async-safe implementation
|
|
114
|
+
|
|
115
|
+
### 3. Retry Strategy
|
|
116
|
+
- Exponential backoff with jitter
|
|
117
|
+
- Configurable delays and attempts
|
|
118
|
+
- Selective retry based on error type
|
|
119
|
+
|
|
120
|
+
### 4. Timeouts
|
|
121
|
+
- Connection timeout: 10 seconds
|
|
122
|
+
- Read timeout: 30 seconds
|
|
123
|
+
- Total timeout: 60 seconds
|
|
124
|
+
|
|
125
|
+
### 5. Caching
|
|
126
|
+
- LRU eviction strategy
|
|
127
|
+
- TTL-based expiration
|
|
128
|
+
- Type-safe cache keys
|
|
129
|
+
|
|
130
|
+
## Data Flow
|
|
131
|
+
|
|
132
|
+
### Search Request Flow
|
|
133
|
+
1. **MCP Client** โ Tool invocation
|
|
134
|
+
2. **FastMCP Server** โ Route to handler
|
|
135
|
+
3. **Tool Handler** โ Validate input
|
|
136
|
+
4. **API Client** โ Check cache
|
|
137
|
+
5. **Rate Limiter** โ Acquire tokens
|
|
138
|
+
6. **Circuit Breaker** โ Check state
|
|
139
|
+
7. **HTTP Client** โ Make request
|
|
140
|
+
8. **Retry Logic** โ Handle failures
|
|
141
|
+
9. **Parser** โ Create domain models
|
|
142
|
+
10. **Cache** โ Store results
|
|
143
|
+
11. **Response** โ Format and return
|
|
144
|
+
|
|
145
|
+
### Error Handling Flow
|
|
146
|
+
1. **Exception** โ Caught at origin
|
|
147
|
+
2. **Logging** โ Structured error log
|
|
148
|
+
3. **Metrics** โ Increment counters
|
|
149
|
+
4. **Circuit Breaker** โ Update state
|
|
150
|
+
5. **Retry** โ Attempt recovery
|
|
151
|
+
6. **Response** โ User-friendly error
|
|
152
|
+
|
|
153
|
+
## Configuration
|
|
154
|
+
|
|
155
|
+
### Environment-Based
|
|
156
|
+
```python
|
|
157
|
+
class Environment(Enum):
|
|
158
|
+
DEVELOPMENT = "development"
|
|
159
|
+
TESTING = "testing"
|
|
160
|
+
STAGING = "staging"
|
|
161
|
+
PRODUCTION = "production"
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Configuration Hierarchy
|
|
165
|
+
1. Default values in code
|
|
166
|
+
2. Configuration files
|
|
167
|
+
3. Environment variables
|
|
168
|
+
4. Runtime parameters
|
|
169
|
+
|
|
170
|
+
### Secrets Management
|
|
171
|
+
- API keys stored as SecretStr
|
|
172
|
+
- Never logged or serialized
|
|
173
|
+
- Loaded from environment
|
|
174
|
+
|
|
175
|
+
## Monitoring & Observability
|
|
176
|
+
|
|
177
|
+
### 1. Structured Logging
|
|
178
|
+
- JSON format for machine parsing
|
|
179
|
+
- Correlation IDs for request tracking
|
|
180
|
+
- Log levels per environment
|
|
181
|
+
- Automatic performance logging
|
|
182
|
+
|
|
183
|
+
### 2. Metrics Collection
|
|
184
|
+
- Request counts by status
|
|
185
|
+
- Response time histograms
|
|
186
|
+
- Cache hit rates
|
|
187
|
+
- Circuit breaker state
|
|
188
|
+
|
|
189
|
+
### 3. Health Checks
|
|
190
|
+
- Liveness: Process is running
|
|
191
|
+
- Readiness: Can serve requests
|
|
192
|
+
- Dependencies: API connectivity
|
|
193
|
+
|
|
194
|
+
### 4. Tracing
|
|
195
|
+
- Correlation IDs across services
|
|
196
|
+
- Request/response logging
|
|
197
|
+
- Performance measurements
|
|
198
|
+
- Error tracking
|
|
199
|
+
|
|
200
|
+
## Security Considerations
|
|
201
|
+
|
|
202
|
+
### 1. Input Validation
|
|
203
|
+
- Pydantic models for all inputs
|
|
204
|
+
- Field-level validation
|
|
205
|
+
- Type checking at boundaries
|
|
206
|
+
|
|
207
|
+
### 2. Rate Limiting
|
|
208
|
+
- Protect against abuse
|
|
209
|
+
- Configurable limits
|
|
210
|
+
- Token bucket algorithm
|
|
211
|
+
|
|
212
|
+
### 3. Error Handling
|
|
213
|
+
- No sensitive data in errors
|
|
214
|
+
- Generic messages to users
|
|
215
|
+
- Detailed logs internally
|
|
216
|
+
|
|
217
|
+
### 4. Configuration
|
|
218
|
+
- Secrets in environment
|
|
219
|
+
- No hardcoded credentials
|
|
220
|
+
- Secure defaults
|
|
221
|
+
|
|
222
|
+
## Performance Optimizations
|
|
223
|
+
|
|
224
|
+
### 1. Caching Strategy
|
|
225
|
+
- Cache search results (5 min)
|
|
226
|
+
- Cache paper details (1 hour)
|
|
227
|
+
- Skip cache for detailed requests
|
|
228
|
+
- LRU eviction
|
|
229
|
+
|
|
230
|
+
### 2. Connection Pooling
|
|
231
|
+
- Persistent HTTP connections
|
|
232
|
+
- Configurable pool size
|
|
233
|
+
- Keep-alive connections
|
|
234
|
+
|
|
235
|
+
### 3. Async Operations
|
|
236
|
+
- Non-blocking I/O throughout
|
|
237
|
+
- Concurrent request handling
|
|
238
|
+
- Efficient resource usage
|
|
239
|
+
|
|
240
|
+
### 4. Batch Operations
|
|
241
|
+
- Batch paper retrieval
|
|
242
|
+
- Reduce API calls
|
|
243
|
+
- Optimize network usage
|
|
244
|
+
|
|
245
|
+
## Testing Strategy
|
|
246
|
+
|
|
247
|
+
### 1. Unit Tests
|
|
248
|
+
- Test individual components
|
|
249
|
+
- Mock external dependencies
|
|
250
|
+
- Focus on business logic
|
|
251
|
+
|
|
252
|
+
### 2. Integration Tests
|
|
253
|
+
- Test component interactions
|
|
254
|
+
- Use test doubles for APIs
|
|
255
|
+
- Verify resilience patterns
|
|
256
|
+
|
|
257
|
+
### 3. Contract Tests
|
|
258
|
+
- Verify API contracts
|
|
259
|
+
- Schema validation
|
|
260
|
+
- Backward compatibility
|
|
261
|
+
|
|
262
|
+
### 4. Performance Tests
|
|
263
|
+
- Load testing
|
|
264
|
+
- Latency measurements
|
|
265
|
+
- Resource usage
|
|
266
|
+
|
|
267
|
+
## Deployment
|
|
268
|
+
|
|
269
|
+
### 1. Dependencies
|
|
270
|
+
- Python >= 3.10
|
|
271
|
+
- uv package manager
|
|
272
|
+
- Environment variables
|
|
273
|
+
|
|
274
|
+
### 2. Running
|
|
275
|
+
```bash
|
|
276
|
+
# Development
|
|
277
|
+
uv run mcp dev
|
|
278
|
+
|
|
279
|
+
# Production
|
|
280
|
+
uv run mcp start
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
### 3. Docker Support
|
|
284
|
+
```dockerfile
|
|
285
|
+
FROM python:3.10-slim
|
|
286
|
+
# Multi-stage build
|
|
287
|
+
# Non-root user
|
|
288
|
+
# Health checks
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
## Future Enhancements
|
|
292
|
+
|
|
293
|
+
### 1. Features
|
|
294
|
+
- WebSocket support for real-time updates
|
|
295
|
+
- GraphQL API integration
|
|
296
|
+
- Advanced search syntax
|
|
297
|
+
- Citation network analysis
|
|
298
|
+
|
|
299
|
+
### 2. Technical
|
|
300
|
+
- Distributed caching (Redis)
|
|
301
|
+
- Message queue integration
|
|
302
|
+
- Horizontal scaling
|
|
303
|
+
- OpenTelemetry integration
|
|
304
|
+
|
|
305
|
+
### 3. Resilience
|
|
306
|
+
- Adaptive circuit breakers
|
|
307
|
+
- Predictive rate limiting
|
|
308
|
+
- Chaos engineering tests
|
|
309
|
+
- Multi-region failover
|