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.
Files changed (66) hide show
  1. semantic_scholar_mcp-0.1.0/.claude/settings.json +43 -0
  2. semantic_scholar_mcp-0.1.0/.env.example +28 -0
  3. semantic_scholar_mcp-0.1.0/.github/dependabot.yml +43 -0
  4. semantic_scholar_mcp-0.1.0/.github/workflows/release.yml +56 -0
  5. semantic_scholar_mcp-0.1.0/.github/workflows/test-pypi.yml +56 -0
  6. semantic_scholar_mcp-0.1.0/.gitignore +160 -0
  7. semantic_scholar_mcp-0.1.0/ARCHITECTURE.md +309 -0
  8. semantic_scholar_mcp-0.1.0/CLAUDE.md +202 -0
  9. semantic_scholar_mcp-0.1.0/LICENSE +21 -0
  10. semantic_scholar_mcp-0.1.0/PKG-INFO +215 -0
  11. semantic_scholar_mcp-0.1.0/README.md +172 -0
  12. semantic_scholar_mcp-0.1.0/docs/ARCHITECTURE.md +715 -0
  13. semantic_scholar_mcp-0.1.0/docs/DEVELOPER_GUIDE.md +1200 -0
  14. semantic_scholar_mcp-0.1.0/docs/USER_GUIDE.md +823 -0
  15. semantic_scholar_mcp-0.1.0/docs/api-specification.yaml +733 -0
  16. semantic_scholar_mcp-0.1.0/docs/uml/01-overview-class-diagram.puml +326 -0
  17. semantic_scholar_mcp-0.1.0/docs/uml/01-overview-class-diagram.svg +1 -0
  18. semantic_scholar_mcp-0.1.0/docs/uml/02-overview-component-diagram.puml +108 -0
  19. semantic_scholar_mcp-0.1.0/docs/uml/02-overview-component-diagram.svg +1 -0
  20. semantic_scholar_mcp-0.1.0/docs/uml/03-overview-deployment-diagram.puml +88 -0
  21. semantic_scholar_mcp-0.1.0/docs/uml/03-overview-deployment-diagram.svg +1 -0
  22. semantic_scholar_mcp-0.1.0/docs/uml/04-flow-paper-search-sequence.puml +126 -0
  23. semantic_scholar_mcp-0.1.0/docs/uml/04-flow-paper-search-sequence.svg +1 -0
  24. semantic_scholar_mcp-0.1.0/docs/uml/05-flow-paper-retrieval-activity.puml +113 -0
  25. semantic_scholar_mcp-0.1.0/docs/uml/05-flow-paper-retrieval-activity.svg +1 -0
  26. semantic_scholar_mcp-0.1.0/docs/uml/06-pattern-circuit-breaker-state.puml +57 -0
  27. semantic_scholar_mcp-0.1.0/docs/uml/06-pattern-circuit-breaker-state.svg +1 -0
  28. semantic_scholar_mcp-0.1.0/docs/uml/README.md +145 -0
  29. semantic_scholar_mcp-0.1.0/pyproject.toml +168 -0
  30. semantic_scholar_mcp-0.1.0/server_standalone.py +14 -0
  31. semantic_scholar_mcp-0.1.0/src/__init__.py +15 -0
  32. semantic_scholar_mcp-0.1.0/src/core/__init__.py +58 -0
  33. semantic_scholar_mcp-0.1.0/src/core/abstractions.py +371 -0
  34. semantic_scholar_mcp-0.1.0/src/core/cache.py +98 -0
  35. semantic_scholar_mcp-0.1.0/src/core/config.py +293 -0
  36. semantic_scholar_mcp-0.1.0/src/core/container.py +363 -0
  37. semantic_scholar_mcp-0.1.0/src/core/exceptions.py +489 -0
  38. semantic_scholar_mcp-0.1.0/src/core/logging.py +358 -0
  39. semantic_scholar_mcp-0.1.0/src/core/metrics.py +572 -0
  40. semantic_scholar_mcp-0.1.0/src/core/missing_types.py +36 -0
  41. semantic_scholar_mcp-0.1.0/src/core/protocols.py +257 -0
  42. semantic_scholar_mcp-0.1.0/src/core/types.py +130 -0
  43. semantic_scholar_mcp-0.1.0/src/main.py +399 -0
  44. semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/__init__.py +7 -0
  45. semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/__main__.py +6 -0
  46. semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/api_client.py +259 -0
  47. semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/api_client_enhanced.py +713 -0
  48. semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/base_models.py +122 -0
  49. semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/domain_models.py +253 -0
  50. semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/models.py +51 -0
  51. semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/models_enhanced.py +851 -0
  52. semantic_scholar_mcp-0.1.0/src/semantic_scholar_mcp/server.py +774 -0
  53. semantic_scholar_mcp-0.1.0/test_api_direct.py +125 -0
  54. semantic_scholar_mcp-0.1.0/test_basic.py +62 -0
  55. semantic_scholar_mcp-0.1.0/test_mcp_tools.py +91 -0
  56. semantic_scholar_mcp-0.1.0/test_readme_functions.py +204 -0
  57. semantic_scholar_mcp-0.1.0/test_search.py +101 -0
  58. semantic_scholar_mcp-0.1.0/test_simple_search.py +96 -0
  59. semantic_scholar_mcp-0.1.0/tests/conftest.py +59 -0
  60. semantic_scholar_mcp-0.1.0/tests/test_http_integration.py.disabled +183 -0
  61. semantic_scholar_mcp-0.1.0/tests/test_integration_mcp.py +300 -0
  62. semantic_scholar_mcp-0.1.0/tests/test_models.py +256 -0
  63. semantic_scholar_mcp-0.1.0/tests/test_real_api.py.disabled +121 -0
  64. semantic_scholar_mcp-0.1.0/tests/test_server_logic.py +131 -0
  65. semantic_scholar_mcp-0.1.0/uml_diagrams.puml +1427 -0
  66. 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