mcp-refcache 0.1.0__tar.gz

mcp_refcache-0.1.0/.env.example

@@ -0,0 +1,57 @@
+# mcp-refcache Configuration
+# Copy this file to .env and customize as needed
+
+# =============================================================================
+# Cache Backend Configuration
+# =============================================================================
+
+# Cache backend type: memory | sqlite | redis (default: memory)
+# CACHE_BACKEND=memory
+
+# SQLite Backend Settings (when CACHE_BACKEND=sqlite)
+# CACHE_SQLITE_PATH=cache.db
+# CACHE_SQLITE_PATH=:memory:  # For testing
+
+# Redis/Valkey Backend Settings (when CACHE_BACKEND=redis)
+# REDIS_URL=redis://localhost:6379/0
+# REDIS_PASSWORD=
+# REDIS_SSL=false
+
+# =============================================================================
+# Preview Configuration
+# =============================================================================
+
+# Maximum preview size in tokens (default: 1024)
+# CACHE_PREVIEW_MAX_SIZE=1024
+
+# Default preview strategy: sample | truncate | paginate (default: sample)
+# CACHE_PREVIEW_STRATEGY=sample
+
+# =============================================================================
+# Namespace & TTL Configuration
+# =============================================================================
+
+# Default namespace for cached values (default: public)
+# CACHE_DEFAULT_NAMESPACE=public
+
+# Default TTL in seconds (default: 3600 = 1 hour)
+# CACHE_DEFAULT_TTL=3600
+
+# =============================================================================
+# Langfuse Observability (optional)
+# =============================================================================
+
+# Enable Langfuse tracing
+# LANGFUSE_PUBLIC_KEY=pk-lf-...
+# LANGFUSE_SECRET_KEY=sk-lf-...
+# LANGFUSE_HOST=https://cloud.langfuse.com
+
+# =============================================================================
+# Development & Debugging
+# =============================================================================
+
+# Log level: DEBUG | INFO | WARNING | ERROR (default: INFO)
+# LOG_LEVEL=INFO
+
+# Enable debug mode for verbose output
+# DEBUG=false

mcp_refcache-0.1.0/.gitignore

@@ -0,0 +1,148 @@
+# Byte-compiled / optimized / DLL files
+archive
+__MACOSX
+
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintainted in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/master/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

mcp_refcache-0.1.0/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+- MCP template (cookiecutter/copier) for new servers with refcache
+- Time series backend for financial data use cases (InfluxDB, TimescaleDB)
+- Redis Cluster/Sentinel support for high availability
+- Metrics/observability hooks (Prometheus, OpenTelemetry)
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+
+#### Core Features
+- **Reference-based caching** - Large values stored by reference, returning previews to agents
+- **`@cache.cached()` decorator** - Simple, Pythonic API for caching tool results
+- **Namespace isolation** - Separate caches for `public`, `session:<id>`, `user:<id>`, custom scopes
+- **Access control** - Fine-grained permissions (READ, WRITE, UPDATE, DELETE, EXECUTE)
+- **Private computation** - EXECUTE permission enables blind computation without data exposure
+- **Preview strategies** - Truncate, sample, or paginate large values
+- **Cross-tool data flow** - References act as a "data bus" between MCP tools
+
+#### Backends
+- **MemoryBackend** - In-memory caching for testing and simple use cases
+- **SQLiteBackend** - Persistent caching with zero external dependencies
+  - WAL mode for concurrent access
+  - Thread-safe with connection-per-thread model
+  - Cross-process reference sharing (multiple MCP servers on same machine)
+  - XDG-compliant default path (`~/.cache/mcp-refcache/cache.db`)
+  - Environment variable override (`MCP_REFCACHE_DB_PATH`)
+- **RedisBackend** - Distributed caching for multi-user/multi-machine scenarios
+  - Valkey/Redis compatible
+  - Native TTL support via Redis expiration
+  - Connection pooling for thread safety
+  - Cross-tool reference sharing verified end-to-end
+  - Docker deployment example with Valkey
+
+#### FastMCP Integration
+- `@cache.cached()` decorator for automatic caching of tool results
+- `cache.resolve()` for cross-tool reference resolution
+- `cache.get()` for preview retrieval with pagination
+- Admin tools for cache management (optional)
+- Cache documentation helpers for tool descriptions
+
+#### Examples
+- `examples/mcp_server.py` - Scientific calculator with sequences and matrices
+- `examples/langfuse_integration.py` - Calculator with Langfuse tracing + SQLite backend
+- `examples/data_tools.py` - Data analysis tools demonstrating cross-tool references
+- `examples/redis-docker/` - Docker Compose setup with Valkey + 2 MCP servers
+
+#### Testing & CI
+- 691+ tests with 80%+ code coverage
+- Parametrized backend tests (Memory, SQLite, Redis)
+- GitHub Actions CI for Python 3.10-3.13
+- Security scanning with Trivy
+- Automated release workflow
+
+### Documentation
+- Comprehensive README with installation and usage examples
+- CONTRIBUTING.md with development guidelines
+- Inline docstrings with examples for all public APIs
+- Docker deployment documentation for Redis backend
+
+## [0.0.1] - Initial Development
+
+### Added
+- Initial project scaffold
+- Core reference-based caching system
+- Memory backend with basic operations
+- Preview generation (truncate, sample, paginate)
+- Pydantic models for type safety
+- Basic test suite
+
+<!-- Uncomment when repository is public
+[Unreleased]: https://github.com/l4b4r4b4b4/mcp-refcache/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/l4b4r4b4b4/mcp-refcache/releases/tag/v0.1.0
+[0.0.1]: https://github.com/l4b4r4b4b4/mcp-refcache/releases/tag/v0.0.1
+-->

mcp_refcache-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 l4b4r4b4b4
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.