├── .gitignore ├── almanac.egg-info ├── dependency_links.txt ├── top_level.txt ├── entry_points.txt ├── requires.txt ├── SOURCES.txt └── PKG-INFO ├── tests ├── __init__.py ├── __pycache__ │ ├── __init__.cpython-310.pyc │ ├── test_crawler.cpython-310.pyc │ ├── test_storage.cpython-310.pyc │ ├── test_mcp_tools.cpython-310.pyc │ ├── test_crawler.cpython-310-pytest-8.3.5.pyc │ ├── test_storage.cpython-310-pytest-8.3.5.pyc │ └── test_mcp_tools.cpython-310-pytest-8.3.5.pyc ├── test_crawler.py └── test_storage.py ├── almanac ├── cli │ ├── __init__.py │ └── __pycache__ │ │ ├── __init__.cpython-310.pyc │ │ ├── __init__.cpython-313.pyc │ │ ├── commands.cpython-310.pyc │ │ └── commands.cpython-313.pyc ├── crawler │ ├── __init__.py │ └── __pycache__ │ │ ├── __init__.cpython-310.pyc │ │ └── adapter.cpython-310.pyc ├── search │ ├── __init__.py │ └── __pycache__ │ │ ├── __init__.cpython-310.pyc │ │ └── text_search.cpython-310.pyc ├── storage │ ├── __init__.py │ └── __pycache__ │ │ ├── __init__.cpython-310.pyc │ │ └── filesystem.cpython-310.pyc ├── mcp │ └── __init__.py ├── tasks │ ├── __pycache__ │ │ ├── queue.cpython-310.pyc │ │ ├── store.cpython-310.pyc │ │ ├── __init__.cpython-310.pyc │ │ ├── models.cpython-310.pyc │ │ └── worker.cpython-310.pyc │ ├── __init__.py │ ├── models.py │ └── store.py ├── __init__.py └── __main__.py ├── tasks.db ├── docs ├── uv-backup │ ├── uv_reference_policies.md │ ├── uv_concepts.md │ ├── uv_reference_benchmarks.md │ ├── uv_reference_troubleshooting.md │ ├── uv_configuration.md │ ├── uv_reference.md │ ├── astral-sh_uv_blob_main_docs_uv.md.md │ ├── uv_guides.md │ ├── uv_guides_integration.md │ ├── uv_getting-started.md │ ├── uv_reference_policies_license.md │ ├── uv_getting-started_first-steps.md │ ├── login.md │ ├── uv_concepts_projects.md │ ├── password_reset.md │ ├── uv_pip_inspection.md │ ├── uv_reference_policies_platforms.md │ ├── uv_pip.md │ ├── uv_pip_dependencies.md │ ├── uv_reference_policies_versioning.md │ ├── signup.md │ ├── uv_getting-started_help.md │ ├── uv_configuration_installer.md │ ├── uv_guides_integration_dependency-bots.md │ ├── uv_guides_integration_pre-commit.md │ ├── solutions_use-case.md │ ├── resources_articles_ai.md │ ├── uv_guides_integration_gitlab.md │ ├── solutions_industry.md │ ├── uv_concepts_projects_build.md │ ├── solutions_use-case_ci-cd.md │ ├── uv_guides_integration_fastapi.md │ ├── solutions_industry_manufacturing.md │ ├── uv_guides_install-python.md │ ├── uv_concepts_projects_layout.md │ ├── uv_concepts_projects_run.md │ ├── solutions.md │ ├── resources_articles.md │ ├── solutions_industry_financial-services.md │ ├── uv_pip_packages.md │ ├── resources_articles_security.md │ ├── resources_articles_software-development.md │ ├── resources_articles_devops.md │ ├── solutions_use-case_devsecops.md │ ├── solutions_use-case_devops.md │ ├── solutions_industry_government.md │ ├── solutions_executive-insights.md │ ├── solutions_industry_nonprofits.md │ ├── features_security.md │ ├── uv_getting-started_features.md │ ├── uv_guides_package.md │ ├── sponsors.md │ ├── uv_configuration_authentication.md │ ├── solutions_industry_healthcare.md │ └── features_code-search.md ├── sources.yaml ├── README.md └── mcp_docs │ ├── development_contributing.md │ ├── development_updates.md │ ├── docs_concepts_roots.md │ ├── tutorials_building-mcp-with-llms.md │ ├── development_roadmap.md │ ├── docs_tools_inspector.md │ └── index.md ├── pyproject.toml ├── memory-bank ├── projectbrief.md ├── productContext.md ├── techContext.md └── progress.md ├── scripts ├── test_mcp_server.py ├── example_workflow.py ├── test_mcp_fastmcp.py └── test_mcp_tools.py ├── .clauderules └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | docs 2 | tasks.db 3 | tasks.md -------------------------------------------------------------------------------- /almanac.egg-info/dependency_links.txt: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /almanac.egg-info/top_level.txt: -------------------------------------------------------------------------------- 1 | almanac 2 | -------------------------------------------------------------------------------- /tests/__init__.py: -------------------------------------------------------------------------------- 1 | """Test suite for TheAlmanac.""" -------------------------------------------------------------------------------- /almanac/cli/__init__.py: -------------------------------------------------------------------------------- 1 | """Command line interface module.""" -------------------------------------------------------------------------------- /almanac/crawler/__init__.py: -------------------------------------------------------------------------------- 1 | """Documentation crawler module.""" -------------------------------------------------------------------------------- /almanac/search/__init__.py: -------------------------------------------------------------------------------- 1 | """Documentation search module.""" -------------------------------------------------------------------------------- /almanac/storage/__init__.py: -------------------------------------------------------------------------------- 1 | """Documentation storage module.""" -------------------------------------------------------------------------------- /almanac/mcp/__init__.py: -------------------------------------------------------------------------------- 1 | """Model Context Protocol integration module.""" -------------------------------------------------------------------------------- /tasks.db: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/tasks.db -------------------------------------------------------------------------------- /almanac.egg-info/entry_points.txt: -------------------------------------------------------------------------------- 1 | [console_scripts] 2 | almanac = almanac.cli.commands:cli 3 | -------------------------------------------------------------------------------- /tests/__pycache__/__init__.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/tests/__pycache__/__init__.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/tasks/__pycache__/queue.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/tasks/__pycache__/queue.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/tasks/__pycache__/store.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/tasks/__pycache__/store.cpython-310.pyc -------------------------------------------------------------------------------- /tests/__pycache__/test_crawler.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/tests/__pycache__/test_crawler.cpython-310.pyc -------------------------------------------------------------------------------- /tests/__pycache__/test_storage.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/tests/__pycache__/test_storage.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/cli/__pycache__/__init__.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/cli/__pycache__/__init__.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/cli/__pycache__/__init__.cpython-313.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/cli/__pycache__/__init__.cpython-313.pyc -------------------------------------------------------------------------------- /almanac/cli/__pycache__/commands.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/cli/__pycache__/commands.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/cli/__pycache__/commands.cpython-313.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/cli/__pycache__/commands.cpython-313.pyc -------------------------------------------------------------------------------- /almanac/tasks/__pycache__/__init__.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/tasks/__pycache__/__init__.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/tasks/__pycache__/models.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/tasks/__pycache__/models.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/tasks/__pycache__/worker.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/tasks/__pycache__/worker.cpython-310.pyc -------------------------------------------------------------------------------- /tests/__pycache__/test_mcp_tools.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/tests/__pycache__/test_mcp_tools.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/crawler/__pycache__/__init__.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/crawler/__pycache__/__init__.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/crawler/__pycache__/adapter.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/crawler/__pycache__/adapter.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/search/__pycache__/__init__.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/search/__pycache__/__init__.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/storage/__pycache__/__init__.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/storage/__pycache__/__init__.cpython-310.pyc -------------------------------------------------------------------------------- /docs/uv-backup/uv_reference_policies.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Policies 3 | * Versioning 4 | * Platform support 5 | * License 6 | 7 | 8 | Back to top 9 | -------------------------------------------------------------------------------- /almanac/search/__pycache__/text_search.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/search/__pycache__/text_search.cpython-310.pyc -------------------------------------------------------------------------------- /almanac/storage/__pycache__/filesystem.cpython-310.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/almanac/storage/__pycache__/filesystem.cpython-310.pyc -------------------------------------------------------------------------------- /tests/__pycache__/test_crawler.cpython-310-pytest-8.3.5.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/tests/__pycache__/test_crawler.cpython-310-pytest-8.3.5.pyc -------------------------------------------------------------------------------- /tests/__pycache__/test_storage.cpython-310-pytest-8.3.5.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/tests/__pycache__/test_storage.cpython-310-pytest-8.3.5.pyc -------------------------------------------------------------------------------- /tests/__pycache__/test_mcp_tools.cpython-310-pytest-8.3.5.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SaharCarmel/TheAlmanac/HEAD/tests/__pycache__/test_mcp_tools.cpython-310-pytest-8.3.5.pyc -------------------------------------------------------------------------------- /almanac.egg-info/requires.txt: -------------------------------------------------------------------------------- 1 | click>=8.0.0 2 | pyyaml>=6.0.0 3 | crawl4ai>=0.4.243 4 | mcp[cli]>=1.5.0 5 | httpx>=0.28.1 6 | 7 | [dev] 8 | pytest>=7.0.0 9 | black>=23.0.0 10 | isort>=5.0.0 11 | -------------------------------------------------------------------------------- /almanac/__init__.py: -------------------------------------------------------------------------------- 1 | """TheAlmanac - Documentation assistant leveraging Model Context Protocol.""" 2 | 3 | __version__ = '0.1.0' 4 | 5 | from almanac.mcp.fastmcp_server import mcp 6 | 7 | __all__ = ['mcp'] 8 | -------------------------------------------------------------------------------- /docs/sources.yaml: -------------------------------------------------------------------------------- 1 | uv: 2 | url: https://github.com/astral-sh/uv/blob/main/docs/uv.md 3 | uv-documentation: 4 | url: https://github.com/astral-sh/uv 5 | uv_docs: 6 | url: https://github.com/astral-sh/uv 7 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_concepts.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Concepts overview 3 | Read the concept documents to learn more about uv's features: 4 | * Projects 5 | * Tools 6 | * Python versions 7 | * Resolution 8 | * Caching 9 | 10 | 11 | Looking for a quick introduction to features? See the guides instead. 12 | Back to top 13 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_reference_benchmarks.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Benchmarks 3 | uv's performance is continually benchmarked against previous releases, and regularly compared to other tools in the space, like pip and Poetry. 4 | The latest benchmarks and details on the benchmarking process can be found in the GitHub repository. 5 | Back to top 6 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_reference_troubleshooting.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Troubleshooting 3 | The troubleshooting section provides information about investigating failures in uv: 4 | * Build failures: Understanding common causes of package build failures. 5 | * Reproducible examples: How to write a minimal reproducible example for a uv issue. 6 | 7 | 8 | Back to top 9 | -------------------------------------------------------------------------------- /almanac.egg-info/SOURCES.txt: -------------------------------------------------------------------------------- 1 | README.md 2 | pyproject.toml 3 | almanac/__init__.py 4 | almanac.egg-info/PKG-INFO 5 | almanac.egg-info/SOURCES.txt 6 | almanac.egg-info/dependency_links.txt 7 | almanac.egg-info/entry_points.txt 8 | almanac.egg-info/requires.txt 9 | almanac.egg-info/top_level.txt 10 | tests/test_crawler.py 11 | tests/test_mcp_tools.py 12 | tests/test_storage.py -------------------------------------------------------------------------------- /almanac/__main__.py: -------------------------------------------------------------------------------- 1 | """Main entry point for the almanac package.""" 2 | from almanac.mcp.fastmcp_server import mcp 3 | 4 | if __name__ == "__main__": 5 | # Configure logging 6 | import logging 7 | logging.basicConfig( 8 | level=logging.INFO, 9 | format="%(asctime)s - %(levelname)s - %(message)s" 10 | ) 11 | 12 | # Run the server 13 | mcp.run() 14 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_configuration.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Configuration overview 3 | Read about the various ways to configure uv: 4 | * Using configuration files 5 | * Using environment variables 6 | * Configuring authentication 7 | * Configuring package indexes 8 | 9 | 10 | Or, jump to the settings reference which enumerates the available configuration options. 11 | Back to top 12 | -------------------------------------------------------------------------------- /almanac/tasks/__init__.py: -------------------------------------------------------------------------------- 1 | """Task management package for TheAlmanac.""" 2 | from almanac.tasks.models import Task, TaskResult, TaskStatus 3 | from almanac.tasks.queue import TaskQueue 4 | from almanac.tasks.store import TaskStore 5 | from almanac.tasks.worker import TaskWorker 6 | 7 | __all__ = [ 8 | "Task", 9 | "TaskResult", 10 | "TaskStatus", 11 | "TaskQueue", 12 | "TaskStore", 13 | "TaskWorker", 14 | ] 15 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_reference.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Reference 3 | The reference section provides information about specific parts of uv: 4 | * Commands: A reference for uv's command line interface. 5 | * Settings: A reference for uv's configuration schema. 6 | * Resolver: Details about the internals of uv's resolver. 7 | * Policies: uv's versioning policy, platform support policy, and license. 8 | 9 | 10 | Looking for a broader overview? Check out the concepts documentation. 11 | Back to top 12 | -------------------------------------------------------------------------------- /docs/uv-backup/astral-sh_uv_blob_main_docs_uv.md.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | astral-sh / **uv ** Public 5 | * Notifications You must be signed in to change notification settings 6 | * Fork 1.3k 7 | * Star 45.7k 8 | 9 | 10 | You can’t perform that action at this time. 11 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_guides.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Guides overview 3 | Check out one of the core guides to get started: 4 | * Installing Python versions 5 | * Running scripts and declaring dependencies 6 | * Running and installing applications as tools 7 | * Creating and working on projects 8 | * Building and publishing packages 9 | * Integrate uv with other software, e.g., Docker, GitHub, PyTorch, and more 10 | 11 | 12 | Or, explore the concept documentation for comprehensive breakdown of each feature. 13 | Back to top 14 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_guides_integration.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Integration guides 3 | Learn how to integrate uv with other software: 4 | * Using in Docker images 5 | * Using with Jupyter 6 | * Using with pre-commit 7 | * Using in GitHub Actions 8 | * Using in GitLab CI/CD 9 | * Using with alternative package indexes 10 | * Installing PyTorch 11 | * Building a FastAPI application 12 | * Using with AWS Lambda 13 | 14 | 15 | Or, explore the concept documentation for comprehensive breakdown of each feature. 16 | Back to top 17 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_getting-started.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Getting started 3 | To help you get started with uv, we'll cover a few important topics: 4 | * Installing uv 5 | * First steps after installation 6 | * An overview of uv's features 7 | * How to get help 8 | 9 | 10 | Read on, or jump ahead to another section: 11 | * Get going quickly with guides for common workflows. 12 | * Learn more about the core concepts in uv. 13 | * Use the reference documentation to find details about something specific. 14 | 15 | 16 | Back to top 17 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_reference_policies_license.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # License 3 | uv is licensed under either of 4 | * Apache License, Version 2.0 5 | 6 | 7 | LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0 8 | * MIT License 9 | 10 | 11 | LICENSE-MIT or https://opensource.org/licenses/MIT 12 | at your option. 13 | Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in uv by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any additional terms or conditions. 14 | Back to top 15 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_getting-started_first-steps.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # First steps with uv 3 | After installing uv, you can check that uv is available by running the `uv` command: 4 | ``` 5 | $ uv 6 | An extremely fast Python package manager. 7 | 8 | Usage: uv [OPTIONS] 9 | 10 | ... 11 | 12 | ``` 13 | 14 | You should see a help menu listing the available commands. 15 | ## Next steps 16 | Now that you've confirmed uv is installed, check out an overview of features, learn how to get help if you run into any problems, or jump to the guides to start using uv. 17 | Back to top 18 | -------------------------------------------------------------------------------- /docs/uv-backup/login.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | # Sign in to GitHub 4 | {{ message }} 5 | Username or email address 6 | Password Forgot password? 7 | ## Password login alternatives 8 | Sign in with a passkey 9 | New to GitHub? Create an account 10 | * Terms 11 | * Privacy 12 | * Docs 13 | * Contact GitHub Support 14 | * Manage cookies 15 | * Do not share my personal information 16 | 17 | 18 | You can’t perform that action at this time. 19 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_concepts_projects.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Projects 3 | Projects help manage Python code spanning multiple files. 4 | Tip 5 | Looking for an introduction to creating a project with uv? See the projects guide first. 6 | Working on projects is a core part of the uv experience. Learn more about using projects: 7 | * Understanding project structure and files 8 | * Creating new projects 9 | * Managing project dependencies 10 | * Running commands and scripts in a project 11 | * Using lockfiles and syncing the environment 12 | * Configuring the project for advanced use cases 13 | * Building distributions to publish a project 14 | * Using workspaces to work on multiple projects at once 15 | 16 | 17 | Back to top 18 | -------------------------------------------------------------------------------- /docs/uv-backup/password_reset.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | # Reset your password 4 | {{ message }} 5 | Enter your user account's verified email address and we will send you a password reset link. 6 | ## Verify your account 7 | ![Waiting for verification.](https://github.githubassets.com/assets/octocat-spinner-128-9d4bc3602169.gif) 8 | * Terms 9 | * Privacy 10 | * Docs 11 | * Contact GitHub Support 12 | * Manage cookies 13 | * Do not share my personal information 14 | 15 | 16 | You can’t perform that action at this time. 17 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # Documentation Directory 2 | 3 | This directory stores documentation downloaded by TheAlmanac. 4 | 5 | ## Structure 6 | 7 | Each documentation source will be stored in its own subdirectory: 8 | 9 | ``` 10 | docs/ 11 | ├── python/ 12 | │ ├── index.md 13 | │ ├── tutorial.md 14 | │ └── ... 15 | ├── react/ 16 | │ ├── index.md 17 | │ ├── components.md 18 | │ └── ... 19 | └── sources.yaml # Configuration file tracking available sources 20 | ``` 21 | 22 | ## Sources File 23 | 24 | The `sources.yaml` file tracks the available documentation sources and their URLs: 25 | 26 | ```yaml 27 | python: 28 | url: https://docs.python.org/3/ 29 | react: 30 | url: https://reactjs.org/docs/ 31 | ``` 32 | 33 | This file is managed automatically by TheAlmanac and should not be edited manually. -------------------------------------------------------------------------------- /docs/uv-backup/uv_pip_inspection.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Inspecting environments 3 | ## Listing installed packages 4 | To list all of the packages in the environment: 5 | ``` 6 | $ uvpiplist 7 | 8 | ``` 9 | 10 | To list the packages in a JSON format: 11 | ``` 12 | $ uvpiplist--formatjson 13 | 14 | ``` 15 | 16 | To list all of the packages in the environment in a `requirements.txt` format: 17 | ``` 18 | $ uvpipfreeze 19 | 20 | ``` 21 | 22 | ## Inspecting a package 23 | To show information about an installed package, e.g., `numpy`: 24 | ``` 25 | $ uvpipshownumpy 26 | 27 | ``` 28 | 29 | Multiple packages can be inspected at once. 30 | ## Verifying an environment 31 | It is possible to install packages with conflicting requirements into an environment if installed in multiple steps. 32 | To check for conflicts or missing dependencies in the environment: 33 | ``` 34 | $ uvpipcheck 35 | 36 | ``` 37 | 38 | Back to top 39 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["setuptools>=61.0"] 3 | build-backend = "setuptools.build_meta" 4 | 5 | [project] 6 | name = "almanac" 7 | version = "0.1.0" 8 | description = "Documentation assistant leveraging Model Context Protocol" 9 | readme = "README.md" 10 | requires-python = ">=3.10" # Updated to 3.10 for MCP compatibility 11 | license = {text = "MIT"} 12 | dependencies = [ 13 | "click>=8.0.0", # CLI framework 14 | "pyyaml>=6.0.0", # YAML parsing 15 | "crawl4ai>=0.4.243", # Web crawling functionality 16 | "mcp[cli]>=1.5.0", 17 | "httpx>=0.28.1", 18 | ] 19 | 20 | [project.optional-dependencies] 21 | dev = [ 22 | "pytest>=7.0.0", 23 | "black>=23.0.0", 24 | "isort>=5.0.0", 25 | ] 26 | 27 | [project.scripts] 28 | almanac = "almanac.cli.commands:cli" 29 | 30 | [tool.setuptools] 31 | packages = ["almanac"] 32 | 33 | [tool.black] 34 | line-length = 88 35 | target-version = ["py310"] # Updated to py310 36 | 37 | [tool.isort] 38 | profile = "black" 39 | line_length = 88 40 | 41 | [dependency-groups] 42 | dev = [ 43 | "black>=25.1.0", 44 | "isort>=6.0.1", 45 | "pytest>=8.3.5", 46 | "pytest-asyncio>=0.25.3", 47 | ] 48 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_reference_policies_platforms.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Platform support 3 | uv has Tier 1 support for the following platforms: 4 | * macOS (Apple Silicon) 5 | * macOS (x86_64) 6 | * Linux (x86_64) 7 | * Windows (x86_64) 8 | 9 | 10 | uv is continuously built, tested, and developed against its Tier 1 platforms. Inspired by the Rust project, Tier 1 can be thought of as "guaranteed to work". 11 | uv has Tier 2 support ("guaranteed to build") for the following platforms: 12 | * Linux (PPC64) 13 | * Linux (PPC64LE) 14 | * Linux (aarch64) 15 | * Linux (armv7) 16 | * Linux (i686) 17 | * Linux (s390x) 18 | 19 | 20 | uv ships pre-built wheels to PyPI for its Tier 1 and Tier 2 platforms. However, while Tier 2 platforms are continuously built, they are not continuously tested or developed against, and so stability may vary in practice. 21 | Beyond the Tier 1 and Tier 2 platforms, uv is known to build on i686 Windows, and known _not_ to build on aarch64 Windows, but does not consider either platform to be supported at this time. The minimum supported Windows versions are Windows 10 and Windows Server 2016, following Rust's own Tier 1 support. 22 | uv supports and is tested against Python 3.8, 3.9, 3.10, 3.11, 3.12, and 3.13. 23 | Back to top 24 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_pip.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # The pip interface 3 | uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. These commands work directly with the virtual environment, in contrast to uv's primary interfaces where the virtual environment is managed automatically. The `uv pip` interface exposes the speed and functionality of uv to power users and projects that are not ready to transition away from `pip` and `pip-tools`. 4 | The following sections discuss the basics of using `uv pip`: 5 | * Creating and using environments 6 | * Installing and managing packages 7 | * Inspecting environments and packages 8 | * Declaring package dependencies 9 | * Locking and syncing environments 10 | 11 | 12 | Please note these commands do not _exactly_ implement the interfaces and behavior of the tools they are based on. The further you stray from common workflows, the more likely you are to encounter differences. Consult the pip-compatibility guide for details. 13 | Important 14 | uv does not rely on or invoke pip. The pip interface is named as such to highlight its dedicated purpose of providing low-level commands that match pip's interface and to separate it from the rest of uv's commands which operate at a higher level of abstraction. 15 | Back to top 16 | -------------------------------------------------------------------------------- /docs/mcp_docs/development_contributing.md: -------------------------------------------------------------------------------- 1 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 2 | Search... 3 | ⌘K 4 | * Python SDK 5 | * TypeScript SDK 6 | * Java SDK 7 | * Kotlin SDK 8 | * Specification 9 | ##### Get Started 10 | * Introduction 11 | * Quickstart 12 | * Example Servers 13 | * Example Clients 14 | 15 | 16 | ##### Tutorials 17 | * Building MCP with LLMs 18 | * Debugging 19 | * Inspector 20 | 21 | 22 | ##### Concepts 23 | * Core architecture 24 | * Resources 25 | * Prompts 26 | * Tools 27 | * Sampling 28 | * Roots 29 | * Transports 30 | 31 | 32 | ##### Development 33 | * What's New 34 | * Roadmap 35 | * Contributing 36 | 37 | 38 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 39 | Search... 40 | ⌘K 41 | Search... 42 | Navigation 43 | Development 44 | Contributing 45 | DocumentationSDKs 46 | DocumentationSDKs 47 | * GitHub 48 | We welcome contributions from the community! Please review our contributing guidelines for details on how to submit changes. 49 | All contributors must adhere to our Code of Conduct. 50 | For questions and discussions, please use GitHub Discussions. 51 | Was this page helpful? 52 | YesNo 53 | Roadmap 54 | -------------------------------------------------------------------------------- /tests/test_crawler.py: -------------------------------------------------------------------------------- 1 | """Tests for the crawler adapter.""" 2 | import asyncio 3 | import os 4 | import shutil 5 | import tempfile 6 | from pathlib import Path 7 | 8 | import pytest 9 | 10 | from almanac.crawler.adapter import DocumentationCrawler 11 | 12 | 13 | @pytest.fixture 14 | def temp_docs_dir(): 15 | """Create a temporary docs directory for testing.""" 16 | temp_dir = tempfile.mkdtemp() 17 | yield temp_dir 18 | shutil.rmtree(temp_dir) 19 | 20 | 21 | def test_crawler_init(temp_docs_dir): 22 | """Test crawler initialization.""" 23 | crawler = DocumentationCrawler(docs_dir=temp_docs_dir) 24 | assert crawler.docs_dir == temp_docs_dir 25 | assert os.path.exists(crawler.sources_file) 26 | 27 | 28 | def test_add_remove_source(temp_docs_dir): 29 | """Test adding and removing a documentation source.""" 30 | crawler = DocumentationCrawler(docs_dir=temp_docs_dir) 31 | 32 | # Test adding a source 33 | crawler.add_source("test", "https://example.com") 34 | sources = crawler.get_sources() 35 | assert "test" in sources 36 | assert sources["test"]["url"] == "https://example.com" 37 | 38 | # Test getting a specific source 39 | source = crawler.get_source("test") 40 | assert source is not None 41 | assert source["url"] == "https://example.com" 42 | 43 | # Test removing a source 44 | crawler.remove_source("test") 45 | sources = crawler.get_sources() 46 | assert "test" not in sources -------------------------------------------------------------------------------- /docs/uv-backup/uv_pip_dependencies.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Declaring dependencies 3 | It is best practice to declare dependencies in a static file instead of modifying environments with ad-hoc installations. Once dependencies are defined, they can be locked to create a consistent, reproducible environment. 4 | ## Using `pyproject.toml` 5 | The `pyproject.toml` file is the Python standard for defining configuration for a project. 6 | To define project dependencies in a `pyproject.toml` file: 7 | pyproject.toml``` 8 | [project] 9 | dependencies=[ 10 | "httpx", 11 | "ruff>=0.3.0" 12 | ] 13 | 14 | ``` 15 | 16 | To define optional dependencies in a `pyproject.toml` file: 17 | pyproject.toml``` 18 | [project.optional-dependencies] 19 | cli=[ 20 | "rich", 21 | "click", 22 | ] 23 | 24 | ``` 25 | 26 | Each of the keys defines an "extra", which can be installed using the `--extra` and `--all-extras` flags or `package[]` syntax. See the documentation on installing packages for more details. 27 | See the official `pyproject.toml` guide for more details on getting started with a `pyproject.toml`. 28 | ## Using `requirements.in` 29 | It is also common to use a lightweight `requirements.txt` format to declare the dependencies for the project. Each requirement is defined on its own line. Commonly, this file is called `requirements.in` to distinguish it from `requirements.txt` which is used for the locked dependencies. 30 | To define dependencies in a `requirements.in` file: 31 | requirements.in``` 32 | httpx 33 | ruff>=0.3.0 34 | 35 | ``` 36 | 37 | Optional dependencies groups are not supported in this format. 38 | Back to top 39 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_reference_policies_versioning.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Versioning 3 | uv uses a custom versioning scheme in which the minor version number is bumped for breaking changes, and the patch version number is bumped for bug fixes, enhancements, and other non-breaking changes. 4 | uv is widely used in production. However, we value the ability to iterate on new features quickly and gather changes that _could_ be breaking into clearly marked releases. 5 | Once uv v1.0.0 is released, the versioning scheme will adhere to Semantic Versioning. There is not a particular goal that must be achieved for uv to reach this milestone. 6 | uv's changelog can be viewed on GitHub. 7 | ## Cache versioning 8 | Cache versions are considered internal to uv, and so may be changed in a minor or patch release. See Cache versioning for more. 9 | ## Lockfile versioning 10 | The `uv.lock` schema version is considered part of the public API, and so will only be incremented in a minor release as a breaking change. See Lockfile versioning for more. 11 | ## Minimum supported Rust version 12 | The minimum supported Rust version required to compile uv is listed in the `rust-version` key of the `[workspace.package]` section in `Cargo.toml`. It may change in any release (minor or patch). It will never be newer than N-2 Rust versions, where N is the latest stable version. For example, if the latest stable Rust version is 1.85, uv's minimum supported Rust version will be at most 1.83. 13 | This is only relevant to users who build uv from source. Installing uv from the Python package index usually installs a pre-built binary and does not require Rust compilation. 14 | Back to top 15 | -------------------------------------------------------------------------------- /docs/uv-backup/signup.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | # Create your free account 5 | Explore GitHub's core features for individuals and organizations. See what's included 6 | * Access to GitHub Copilot Increase your productivity and accelerate software development. 7 | * Unlimited repositories Collaborate securely on public and private projects. 8 | * Integrated code reviews Boost code quality with built-in review tools. 9 | * Automated workflows Save time with CI/CD integrations and GitHub Actions. 10 | * Community support Connect with developers worldwide for instant feedback and insights. 11 | 12 | 13 | ![GitHub Mascots: Mona, Copilot, and a rubber duck floating on top of an astral background of stars.](https://github.githubassets.com/assets/dos-amigos@2x-5f31ce5f49b4.webp) 14 | ## Sign up to GitHub 15 | Email* 16 | Password* 17 | Password should be at least 15 characters OR at least 8 characters including a number and a lowercase letter. 18 | Username* 19 | Username may only contain alphanumeric characters or single hyphens, and cannot begin or end with a hyphen. 20 | Continue 21 | ## Verify your account 22 | ![Waiting for verification.](https://github.githubassets.com/assets/octocat-spinner-128-9d4bc3602169.gif) 23 | Create account 24 | By creating an account, you agree to the Terms of Service. For more information about GitHub's privacy practices, see the GitHub Privacy Statement. We'll occasionally send you account-related emails. 25 | You can’t perform that action at this time. 26 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_getting-started_help.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Getting help 3 | ## Help menus 4 | The `--help` flag can be used to view the help menu for a command, e.g., for `uv`: 5 | ``` 6 | $ uv--help 7 | 8 | ``` 9 | 10 | To view the help menu for a specific command, e.g., for `uv init`: 11 | ``` 12 | $ uvinit--help 13 | 14 | ``` 15 | 16 | When using the `--help` flag, uv displays a condensed help menu. To view a longer help menu for a command, use `uv help`: 17 | ``` 18 | $ uvhelp 19 | 20 | ``` 21 | 22 | To view the long help menu for a specific command, e.g., for `uv init`: 23 | ``` 24 | $ uvhelpinit 25 | 26 | ``` 27 | 28 | When using the long help menu, uv will attempt to use `less` or `more` to "page" the output so it is not all displayed at once. To exit the pager, press `q`. 29 | ## Viewing the version 30 | When seeking help, it's important to determine the version of uv that you're using — sometimes the problem is already solved in a newer version. 31 | To check the installed version: 32 | ``` 33 | $ uvversion 34 | 35 | ``` 36 | 37 | The following are also valid: 38 | ``` 39 | $ uv--version# Same output as `uv version` 40 | $ uv-V# Will not include the build commit and date 41 | $ uvpip--version# Can be used with a subcommand 42 | 43 | ``` 44 | 45 | ## Troubleshooting issues 46 | The reference documentation contains a troubleshooting guide for common issues. 47 | ## Open an issue on GitHub 48 | The issue tracker on GitHub is a good place to report bugs and request features. Make sure to search for similar issues first, as it is common for someone else to encounter the same problem. 49 | ## Chat on Discord 50 | Astral has a Discord server, which is a great place to ask questions, learn more about uv, and engage with other community members. 51 | Back to top 52 | -------------------------------------------------------------------------------- /almanac/tasks/models.py: -------------------------------------------------------------------------------- 1 | """Data models for task management.""" 2 | from dataclasses import dataclass 3 | from datetime import datetime 4 | from enum import Enum 5 | from typing import Any, Dict, Optional 6 | from uuid import UUID, uuid4 7 | 8 | 9 | class TaskStatus(Enum): 10 | """Possible states for a task.""" 11 | PENDING = "PENDING" 12 | RUNNING = "RUNNING" 13 | COMPLETED = "COMPLETED" 14 | FAILED = "FAILED" 15 | 16 | 17 | @dataclass 18 | class Task: 19 | """Represents a background task.""" 20 | id: UUID 21 | type: str 22 | params: Dict[str, Any] 23 | status: TaskStatus 24 | created_at: datetime 25 | updated_at: datetime 26 | progress: float = 0.0 27 | message: str = "" 28 | result_id: Optional[UUID] = None 29 | 30 | @classmethod 31 | def create(cls, task_type: str, params: Dict[str, Any]) -> "Task": 32 | """Create a new task.""" 33 | now = datetime.utcnow() 34 | return cls( 35 | id=uuid4(), 36 | type=task_type, 37 | params=params, 38 | status=TaskStatus.PENDING, 39 | created_at=now, 40 | updated_at=now 41 | ) 42 | 43 | 44 | @dataclass 45 | class TaskResult: 46 | """Represents the result of a completed task.""" 47 | id: UUID 48 | task_id: UUID 49 | content: str 50 | error: Optional[str] = None 51 | created_at: datetime = datetime.utcnow() 52 | 53 | @classmethod 54 | def create( 55 | cls, task_id: UUID, content: str, error: Optional[str] = None 56 | ) -> "TaskResult": 57 | """Create a new task result.""" 58 | return cls( 59 | id=uuid4(), 60 | task_id=task_id, 61 | content=content, 62 | error=error 63 | ) 64 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_configuration_installer.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Configuring the uv installer 3 | ## Changing the install path 4 | By default, uv is installed to `~/.local/bin`. If `XDG_BIN_HOME` is set, it will be used instead. Similarly, if `XDG_DATA_HOME` is set, the target directory will be inferred as `XDG_DATA_HOME/../bin`. 5 | To change the installation path, use `UV_INSTALL_DIR`: 6 | macOS and LinuxWindows 7 | ``` 8 | $ curl-LsSfhttps://astral.sh/uv/install.sh|envUV_INSTALL_DIR="/custom/path"sh 9 | 10 | ``` 11 | 12 | ``` 13 | powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "C:\Custom\Path";irm https://astral.sh/uv/install.ps1 | iex} 14 | 15 | ``` 16 | 17 | ## Disabling shell modifications 18 | The installer may also update your shell profiles to ensure the uv binary is on your `PATH`. To disable this behavior, use `INSTALLER_NO_MODIFY_PATH`. For example: 19 | ``` 20 | $ curl-LsSfhttps://astral.sh/uv/install.sh|envINSTALLER_NO_MODIFY_PATH=1sh 21 | 22 | ``` 23 | 24 | If installed with `INSTALLER_NO_MODIFY_PATH`, subsequent operations, like `uv self update`, will not modify your shell profiles. 25 | ## Unmanaged installations 26 | In ephemeral environments like CI, use `UV_UNMANAGED_INSTALL` to install uv to a specific path while preventing the installer from modifying shell profiles or environment variables: 27 | ``` 28 | $ curl-LsSfhttps://astral.sh/uv/install.sh|envUV_UNMANAGED_INSTALL="/custom/path"sh 29 | 30 | ``` 31 | 32 | The use of `UV_UNMANAGED_INSTALL` will also disable self-updates (via `uv self update`). 33 | ## Passing options to the install script 34 | Using environment variables is recommended because they are consistent across platforms. However, options can be passed directly to the install script. For example, to see the available options: 35 | ``` 36 | $ curl-LsSfhttps://astral.sh/uv/install.sh|sh-s----help 37 | 38 | ``` 39 | 40 | Back to top 41 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_guides_integration_dependency-bots.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Dependency bots 3 | It is considered best practice to regularly update dependencies, to avoid being exposed to vulnerabilities, limit incompatibilities between dependencies, and avoid complex upgrades when upgrading from a too old version. A variety of tools can help staying up-to-date by creating automated pull requests. Several of them support uv, or have work underway to support it. 4 | ## Renovate 5 | uv is supported by Renovate. 6 | Note 7 | Updating `uv pip compile` outputs such as `requirements.txt` is not yet supported. Progress can be tracked at renovatebot/renovate#30909. 8 | ### `uv.lock` output 9 | Renovate uses the presence of a `uv.lock` file to determine that uv is used for managing dependencies, and will suggest upgrades to project dependencies, optional dependencies and development dependencies. Renovate will update both the `pyproject.toml` and `uv.lock` files. 10 | The lockfile can also be refreshed on a regular basis (for instance to update transitive dependencies) by enabling the `lockFileMaintenance` option: 11 | renovate.json5``` 12 | { 13 | $schema:"https://docs.renovatebot.com/renovate-schema.json", 14 | lockFileMaintenance:{ 15 | enabled:true, 16 | }, 17 | } 18 | 19 | ``` 20 | 21 | ### Inline script metadata 22 | Renovate supports updating dependencies defined using script inline metadata. 23 | Since it cannot automatically detect which Python files use script inline metadata, their locations need to be explicitly defined using `fileMatch`, like so: 24 | renovate.json5``` 25 | { 26 | $schema:"https://docs.renovatebot.com/renovate-schema.json", 27 | pep723:{ 28 | fileMatch:[ 29 | "scripts/generate_docs\\.py", 30 | "scripts/run_server\\.py", 31 | ], 32 | }, 33 | } 34 | 35 | ``` 36 | 37 | ## Dependabot 38 | Support for uv is not yet available. Progress can be tracked at dependabot/dependabot-core#10478. 39 | Back to top 40 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_guides_integration_pre-commit.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Using uv in pre-commit 3 | An official pre-commit hook is provided at `astral-sh/uv-pre-commit`. 4 | To make sure your `uv.lock` file is up to date even if your `pyproject.toml` file was changed via pre-commit, add the following to the `.pre-commit-config.yaml`: 5 | .pre-commit-config.yaml``` 6 | repos: 7 | -repo:https://github.com/astral-sh/uv-pre-commit 8 | # uv version. 9 | rev:0.6.9 10 | hooks: 11 | -id:uv-lock 12 | 13 | ``` 14 | 15 | To keep your `requirements.txt` file updated using pre-commit: 16 | .pre-commit-config.yaml``` 17 | repos: 18 | -repo:https://github.com/astral-sh/uv-pre-commit 19 | # uv version. 20 | rev:0.6.9 21 | hooks: 22 | -id:uv-export 23 | 24 | ``` 25 | 26 | To compile requirements via pre-commit, add the following to the `.pre-commit-config.yaml`: 27 | .pre-commit-config.yaml``` 28 | repos: 29 | -repo:https://github.com/astral-sh/uv-pre-commit 30 | # uv version. 31 | rev:0.6.9 32 | hooks: 33 | # Compile requirements 34 | -id:pip-compile 35 | args:[requirements.in,-o,requirements.txt] 36 | 37 | ``` 38 | 39 | To compile alternative files, modify `args` and `files`: 40 | .pre-commit-config.yaml``` 41 | repos: 42 | -repo:https://github.com/astral-sh/uv-pre-commit 43 | # uv version. 44 | rev:0.6.9 45 | hooks: 46 | # Compile requirements 47 | -id:pip-compile 48 | args:[requirements-dev.in,-o,requirements-dev.txt] 49 | files:^requirements-dev\.(in|txt)$ 50 | 51 | ``` 52 | 53 | To run the hook over multiple files at the same time: 54 | .pre-commit-config.yaml``` 55 | repos: 56 | -repo:https://github.com/astral-sh/uv-pre-commit 57 | # uv version. 58 | rev:0.6.9 59 | hooks: 60 | # Compile requirements 61 | -id:pip-compile 62 | name:pip-compile requirements.in 63 | args:[requirements.in,-o,requirements.txt] 64 | -id:pip-compile 65 | name:pip-compile requirements-dev.in 66 | args:[requirements-dev.in,-o,requirements-dev.txt] 67 | files:^requirements-dev\.(in|txt)$ 68 | 69 | ``` 70 | 71 | Back to top 72 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_use-case.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | Solutions 5 | Use Cases 6 | # GitHub solutions 7 | Solve your business challenges with proven combinations of GitHub solutions, empowering your team to ship secure software quickly and accelerate innovation. 8 | Start a free trialContact sales 9 | ### DevSecOps 10 | With comprehensive security tools built into the developer workflow, you can build, secure, and ship all in one place. 11 | Learn more 12 | ### DevOps 13 | Scale and deliver more secure software with GitHub's unified AI-powered developer platform. 14 | Learn more 15 | ### CI/CD 16 | Test and deploy software with simple and secure enterprise CI/CD. 17 | Learn more 18 | ## Related solutions 19 | ### Healthcare 20 | By incorporating security checks into developer workflows, you can build secure communication channels between patients and providers. 21 | Learn more 22 | ### Financial Services 23 | With an AI-powered developer platform, you can build innovative financial solutions that drive economic growth. 24 | Learn more 25 | ### Manufacturing 26 | With robust CI/CD that can handle the complex needs of manufacturing, you can securely transform operations at scale. 27 | Learn more 28 | ### 2.4xmore precise leaked secrets found with fewer false positives 29 | ### ~25%increase in developer speed with GitHub Copilot 30 | ### 1minset-up time for largest repo with GitHub Codespaces 31 | ### +88%more productivity with GitHub Enterprise 32 | ### Get started 33 | Trusted by 90% of the Fortune 100, GitHub helps millions of developers and companies collaborate, build, and deliver secure software faster. And with thousands of DevOps integrations, developers can build smarter from day one with the tools they know and love—or discover new ones. 34 | Start a free trialContact sales 35 | You can’t perform that action at this time. 36 | -------------------------------------------------------------------------------- /docs/uv-backup/resources_articles_ai.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | # AI 5 | ## Topics 6 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 7 | ### Natural language processing (NLP) in software development 8 | Learn why natural language processing (NLP) is becoming an indispensable tool for developers. 9 | Learn more 10 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 11 | ### What are AI models? 12 | Learn how AI models help organizations identify data patterns, automate workflows, solve complex problems, forecast outcomes, and enhance decision making. 13 | Learn more 14 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 15 | ### Enhancing software development with retrieval-augmented generation 16 | Learn how Retrieval Augmented Generation (RAG) improves coding, debugging, and code reviews. 17 | Learn more 18 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 19 | ### What are AI agents? 20 | Discover how AI agents transform software development by automating workflows and enhancing security. Explore the different types of AI agents, learn how they integrate into development environments, and see real-world examples of their impact. Learn best practices for using AI agents and get a glimpse into the future of AI in development and security. 21 | Learn more 22 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 23 | ### What is AI code generation? 24 | AI code generation uses machine learning models to provide context-based code suggestions. 25 | Learn more 26 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 27 | ### AI coding tools for beginner and expert coders 28 | How beginner and expert coders use AI coding tools to code faster and ship great software. 29 | Learn more 30 | You can’t perform that action at this time. 31 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_guides_integration_gitlab.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Using uv in GitLab CI/CD 3 | ## Using the uv image 4 | Astral provides Docker images with uv preinstalled. Select a variant that is suitable for your workflow. 5 | gitlab-ci.yml``` 6 | variables: 7 | UV_VERSION:0.5 8 | PYTHON_VERSION:3.12 9 | BASE_LAYER:bookworm-slim 10 | # GitLab CI creates a separate mountpoint for the build directory, 11 | # so we need to copy instead of using hard links. 12 | UV_LINK_MODE:copy 13 | 14 | uv: 15 | image:ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER 16 | script: 17 | # your `uv` commands 18 | 19 | ``` 20 | 21 | Note 22 | If you are using a distroless image, you have to specify the entrypoint: 23 | ``` 24 | uv: 25 | image: 26 | name:ghcr.io/astral-sh/uv:$UV_VERSION 27 | entrypoint:[""] 28 | # ... 29 | 30 | ``` 31 | 32 | ## Caching 33 | Persisting the uv cache between workflow runs can improve performance. 34 | ``` 35 | uv-install: 36 | variables: 37 | UV_CACHE_DIR:.uv-cache 38 | cache: 39 | -key: 40 | files: 41 | -uv.lock 42 | paths: 43 | -$UV_CACHE_DIR 44 | script: 45 | # Your `uv` commands 46 | -uv cache prune --ci 47 | 48 | ``` 49 | 50 | See the GitLab caching documentation for more details on configuring caching. 51 | Using `uv cache prune --ci` at the end of the job is recommended to reduce cache size. See the uv cache documentation for more details. 52 | ## Using `uv pip` 53 | If using the `uv pip` interface instead of the uv project interface, uv requires a virtual environment by default. To allow installing packages into the system environment, use the `--system` flag on all uv invocations or set the `UV_SYSTEM_PYTHON` variable. 54 | The `UV_SYSTEM_PYTHON` variable can be defined in at different scopes. You can read more about how variables and their precedence works in GitLab here 55 | Opt-in for the entire workflow by defining it at the top level: 56 | gitlab-ci.yml``` 57 | variables: 58 | UV_SYSTEM_PYTHON:1 59 | 60 | # [...] 61 | 62 | ``` 63 | 64 | To opt-out again, the `--no-system` flag can be used in any uv invocation. 65 | When persisting the cache, you may want to use `requirements.txt` or `pyproject.toml` as your cache key files instead of `uv.lock`. 66 | Back to top 67 | -------------------------------------------------------------------------------- /memory-bank/projectbrief.md: -------------------------------------------------------------------------------- 1 | # Project Brief: TheAlmanac 2 | 3 | ## Vision 4 | TheAlmanac is a tool leveraging the Model Context Protocol (MCP) to help programmers efficiently access relevant information from API and software documentation. It serves as a smart documentation assistant that eliminates the friction between developers and the documentation they need. 5 | 6 | ## Core Goals 7 | 1. **Automated Documentation Retrieval**: Scrape and locally store documentation upon request 8 | 2. **Intelligent Information Extraction**: Enable targeted queries to retrieve only relevant documentation sections 9 | 3. **Progressive Intelligence**: Start with naive implementation, then enhance with RAG or other LLM techniques 10 | 4. **Cloud Capability**: Provide option to connect to remote server with pre-stored documentation 11 | 12 | ## Success Criteria 13 | - Developers can request new documentation and have it automatically downloaded 14 | - Specific queries return precise, relevant documentation sections 15 | - System works efficiently with local storage 16 | - Optional remote server connection reduces need for local documentation storage 17 | - Open source availability with clear contribution guidelines 18 | 19 | ## Development Phases 20 | 21 | ### Phase 1: Foundation 22 | - Setup project structure 23 | - Implement naive documentation scraper 24 | - Create local storage system 25 | - Develop basic query functionality 26 | 27 | ### Phase 2: Intelligence 28 | - Implement RAG or other LLM techniques for smarter responses 29 | - Enhance query capabilities 30 | - Optimize local storage 31 | 32 | ### Phase 3: Cloud Connectivity 33 | - Create remote server capability 34 | - Implement secure connection methods 35 | - Develop synchronization between local and remote documentation 36 | 37 | ### Phase 4: Open Source Release 38 | - Complete documentation 39 | - Create contribution guidelines 40 | - Publish open source repository 41 | 42 | ## Technical Considerations 43 | - Documentation formats vary widely (HTML, PDF, Markdown, etc.) 44 | - Storage efficiency for potentially large documentation sets 45 | - Security considerations for remote connections 46 | - Cross-platform compatibility 47 | - MCP integration for LLM context management -------------------------------------------------------------------------------- /docs/mcp_docs/development_updates.md: -------------------------------------------------------------------------------- 1 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 2 | Search... 3 | ⌘K 4 | * Python SDK 5 | * TypeScript SDK 6 | * Java SDK 7 | * Kotlin SDK 8 | * Specification 9 | ##### Get Started 10 | * Introduction 11 | * Quickstart 12 | * Example Servers 13 | * Example Clients 14 | 15 | 16 | ##### Tutorials 17 | * Building MCP with LLMs 18 | * Debugging 19 | * Inspector 20 | 21 | 22 | ##### Concepts 23 | * Core architecture 24 | * Resources 25 | * Prompts 26 | * Tools 27 | * Sampling 28 | * Roots 29 | * Transports 30 | 31 | 32 | ##### Development 33 | * What's New 34 | * Roadmap 35 | * Contributing 36 | 37 | 38 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 39 | Search... 40 | ⌘K 41 | Search... 42 | Navigation 43 | Development 44 | What's New 45 | DocumentationSDKs 46 | DocumentationSDKs 47 | * GitHub 48 | ​ 49 | 2025-02-14 50 | Java SDK released 51 | * We’re excited to announce that the Java SDK developed by Spring AI at VMware Tanzu is now the official Java SDK for MCP. This joins our existing Kotlin SDK in our growing list of supported languages. The Spring AI team will maintain the SDK as an integral part of the Model Context Protocol organization. We’re thrilled to welcome them to the MCP community! 52 | 53 | 54 | ​ 55 | 2025-01-27 56 | Python SDK 1.2.1 57 | * Version 1.2.1 of the MCP Python SDK has been released, delivering important stability improvements and bug fixes. 58 | 59 | 60 | ​ 61 | 2025-01-18 62 | SDK and Server Improvements 63 | * Simplified, express-like API in the TypeScript SDK 64 | * Added 8 new clients to the clients page 65 | 66 | 67 | ​ 68 | 2025-01-03 69 | SDK and Server Improvements 70 | * FastMCP API in the Python SDK 71 | * Dockerized MCP servers in the servers repo 72 | 73 | 74 | ​ 75 | 2024-12-21 76 | Kotlin SDK released 77 | * Jetbrains released a Kotlin SDK for MCP! 78 | * For a sample MCP Kotlin server, check out this repository 79 | 80 | 81 | Was this page helpful? 82 | YesNo 83 | TransportsRoadmap 84 | On this page 85 | * 2025-02-14 86 | * 2025-01-27 87 | * 2025-01-18 88 | * 2025-01-03 89 | * 2024-12-21 90 | 91 | 92 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_industry.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | Solutions 5 | Industries 6 | # Industry solutions 7 | Discover how GitHub’s industry solutions can help you improve efficiency, reduce costs, and capture new market opportunities. 8 | Start a free trialContact sales 9 | ### Healthcare 10 | By incorporating security checks into developer workflows, you can build secure communication channels between patients and providers. 11 | Learn more 12 | ### Financial Services 13 | With an AI-powered developer platform, you can build innovative financial solutions that drive economic growth. 14 | Learn more 15 | ### Manufacturing 16 | With robust CI/CD that can handle the complex needs of manufacturing, you can securely transform operations at scale. 17 | Learn more 18 | ### Government 19 | With seamless collaboration and robust compliance, GitHub helps government agencies build and innovate securely on a single, AI-powered platform. 20 | Learn more 21 | ## Related solutions 22 | ### DevSecOps 23 | With comprehensive security tools built into the developer workflow, you can build, secure, and ship all in one place. 24 | Learn more 25 | ### DevOps 26 | Scale and deliver more secure software with GitHub's unified AI-powered developer platform. 27 | Learn more 28 | ### CI/CD 29 | Test and deploy software with simple and secure enterprise CI/CD. 30 | Learn more 31 | ### Executive Insights 32 | Get expert perspectives. Stay ahead with insights from industry leaders. 33 | Learn more 34 | Gartner 35 | Narrow your DevOps platform search with this Gartner report 36 | Read the report 37 | ### 2.4xmore precise leaked secrets found with fewer false positives 38 | ### ~25%increase in developer speed with GitHub Copilot 39 | ### 1minset-up time for largest repo with GitHub Codespaces 40 | ### +88%more productivity with GitHub Enterprise 41 | ### Get started 42 | Trusted by 90% of the Fortune 100, GitHub helps millions of developers and companies collaborate, build, and deliver secure software faster. And with thousands of DevOps integrations, developers can build smarter from day one with the tools they know and love—or discover new ones. 43 | Start a free trialContact sales 44 | You can’t perform that action at this time. 45 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_concepts_projects_build.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Building distributions 3 | To distribute your project to others (e.g., to upload it to an index like PyPI), you'll need to build it into a distributable format. 4 | Python projects are typically distributed as both source distributions (sdists) and binary distributions (wheels). The former is typically a `.tar.gz` or `.zip` file containing the project's source code along with some additional metadata, while the latter is a `.whl` file containing pre-built artifacts that can be installed directly. 5 | Important 6 | When using `uv build`, uv acts as a build frontend and only determines the Python version to use and invokes the build backend. The details of the builds, such as the included files and the distribution filenames, are determined by the build backend, as defined in `[build-system]`. Information about build configuration can be found in the respective tool's documentation. 7 | ## Using `uv build` 8 | `uv build` can be used to build both source distributions and binary distributions for your project. By default, `uv build` will build the project in the current directory, and place the built artifacts in a `dist/` subdirectory: 9 | ``` 10 | $ uvbuild 11 | $ lsdist/ 12 | example-0.1.0-py3-none-any.whl 13 | example-0.1.0.tar.gz 14 | 15 | ``` 16 | 17 | You can build the project in a different directory by providing a path to `uv build`, e.g., `uv build path/to/project`. 18 | `uv build` will first build a source distribution, and then build a binary distribution (wheel) from that source distribution. 19 | You can limit `uv build` to building a source distribution with `uv build --sdist`, a binary distribution with `uv build --wheel`, or build both distributions from source with `uv build --sdist --wheel`. 20 | ## Build constraints 21 | `uv build` accepts `--build-constraint`, which can be used to constrain the versions of any build requirements during the build process. When coupled with `--require-hashes`, uv will enforce that the requirement used to build the project match specific, known hashes, for reproducibility. 22 | For example, given the following `constraints.txt`: 23 | ``` 24 | setuptools==68.2.2 --hash=sha256:b454a35605876da60632df1a60f736524eb73cc47bbc9f3f1ef1b644de74fd2a 25 | 26 | ``` 27 | 28 | Running the following would build the project with the specified version of `setuptools`, and verify that the downloaded `setuptools` distribution matches the specified hash: 29 | ``` 30 | $ uvbuild--build-constraintconstraints.txt--require-hashes 31 | 32 | ``` 33 | 34 | Back to top 35 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_use-case_ci-cd.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | GitHub CI/CD 5 | # The complete CI/CD solution 6 | Build, test, and deploy software with simple and secure enterprise CI/CD, all on the complete development platform. 7 | Start a free trialContact sales 8 | ![Tests with checkmarks beside each test title and an activated merge pull request button](https://images.ctfassets.net/8aevphvgewt8/6cuxKTqIN1l0NMxSNlx15F/7d746be47686a08fbc09219bc63df0e5/Hero2.webp?fm=webp) 9 | ### Turn code into software 10 | Automatically trigger builds on every commit with workflow builder. 11 | ### Secure and improve 12 | End-to-end testing for security, code quality, performance, and functionality. 13 | ### Ship with confidence 14 | Automate deployments from start to finish to one or multiple cloud providers. 15 | ### Build fast, stay secure 16 | Easy-to-set-up and simple-to-maintain CI/CD that helps your developers build more secure code from the start without sacrificing speed. 17 | Explore GitHub Advanced Security 18 | ![](https://images.ctfassets.net/8aevphvgewt8/4pufdRqmUtEHxCRy4SbGq6/566eeeb0beee0f3b8c92fb3831d2290d/Security-2.webp) 19 | ### Continuous testing made simple 20 | Track everything from code quality to your security profile with end-to-end testing built to keep you secure and in compliance at every stage. 21 | ![Test passing connecting to 3 steps that are in progress](https://images.ctfassets.net/8aevphvgewt8/7JldMWj69GEj43gx9cIf5K/4d53dbc663417142a5dd826c79d4215f/Automation-2.webp) 22 | ### Deploy software with confidence 23 | Seamless CI/CD deployment automation makes it simple to deliver secure software with all cloud providers so you can scale confidently. 24 | Explore GitHub Actions 25 | ![](https://images.ctfassets.net/8aevphvgewt8/10miox7JNqtL3gGpCf1sRS/d0923ff169cd8d2015174a51d503c09e/AI-2.webp) 26 | ### 90%+Fortune 100 choose GitHub 27 | ### 100M+Developers call GitHub home 28 | ### 420M+Repositories on GitHub 29 | ### Powerful CI/CD with GitHub Enterprise 30 | The complete developer platform to build, scale, and deliver secure software. 31 | Start a free trialContact sales 32 | ### Additional resources 33 | ### DevOps tips for Engineering leaders 34 | 6 DevOps tips to help engineering leaders deliver software at scale 35 | Get the report 36 | ### Ship secure software fast 37 | How developer-first supply chain security helps you secure faster 38 | Get the report 39 | ### CI/CD Solution Demo 40 | How to automate CI/CD and security with GitHub Enterprise 41 | Get the report 42 | You can’t perform that action at this time. 43 | -------------------------------------------------------------------------------- /scripts/test_mcp_server.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """Test script for MCP server.""" 3 | import argparse 4 | import json 5 | import logging 6 | import sys 7 | import urllib.request 8 | import urllib.error 9 | from pathlib import Path 10 | 11 | # Configure logging 12 | logging.basicConfig( 13 | level=logging.INFO, 14 | format="%(asctime)s - %(levelname)s - %(message)s" 15 | ) 16 | logger = logging.getLogger(__name__) 17 | 18 | 19 | def get_tools(host: str = "localhost", port: int = 8000): 20 | """Get tools from the MCP server.""" 21 | url = f"http://{host}:{port}/tools" 22 | 23 | try: 24 | with urllib.request.urlopen(url) as response: 25 | data = json.loads(response.read().decode("utf-8")) 26 | return data 27 | except urllib.error.URLError as e: 28 | logger.error(f"Error getting tools: {str(e)}") 29 | return None 30 | 31 | 32 | def execute_tool( 33 | tool_name: str, params: dict, host: str = "localhost", port: int = 8000 34 | ): 35 | """Execute a tool on the MCP server.""" 36 | url = f"http://{host}:{port}/execute" 37 | 38 | request_data = { 39 | "tool": tool_name, 40 | "params": params 41 | } 42 | 43 | request_body = json.dumps(request_data).encode("utf-8") 44 | 45 | req = urllib.request.Request( 46 | url, 47 | data=request_body, 48 | headers={"Content-Type": "application/json"} 49 | ) 50 | 51 | try: 52 | with urllib.request.urlopen(req) as response: 53 | data = json.loads(response.read().decode("utf-8")) 54 | return data 55 | except urllib.error.URLError as e: 56 | logger.error(f"Error executing tool: {str(e)}") 57 | return None 58 | 59 | 60 | def main(): 61 | """Main function.""" 62 | parser = argparse.ArgumentParser(description="Test MCP server") 63 | parser.add_argument("--host", default="localhost", help="Server host") 64 | parser.add_argument("--port", type=int, default=8000, help="Server port") 65 | 66 | subparsers = parser.add_subparsers(dest="command", help="Command to run") 67 | 68 | # Get tools 69 | tools_parser = subparsers.add_parser("tools", help="Get available tools") 70 | 71 | # Execute tool 72 | execute_parser = subparsers.add_parser("execute", help="Execute a tool") 73 | execute_parser.add_argument("tool", help="Tool name") 74 | execute_parser.add_argument("params", help="Tool parameters (JSON string)") 75 | 76 | args = parser.parse_args() 77 | 78 | if args.command == "tools": 79 | tools = get_tools(args.host, args.port) 80 | if tools: 81 | print(json.dumps(tools, indent=2)) 82 | elif args.command == "execute": 83 | params = json.loads(args.params) 84 | result = execute_tool(args.tool, params, args.host, args.port) 85 | if result: 86 | print(json.dumps(result, indent=2)) 87 | else: 88 | parser.print_help() 89 | 90 | 91 | if __name__ == "__main__": 92 | main() -------------------------------------------------------------------------------- /memory-bank/productContext.md: -------------------------------------------------------------------------------- 1 | # Product Context 2 | 3 | ## Problem Statement 4 | LLMs and AI coding assistants like Claude Code have knowledge cutoffs that limit their ability to provide up-to-date solutions. This leads to recommendations that may be outdated, deprecated, or simply not optimal given the current state of libraries, frameworks, and APIs. Developers often need to manually correct these solutions, reducing productivity and trust in AI tools. 5 | 6 | ## User Needs 7 | - Access to the most current API and software documentation for LLMs 8 | - Ability for LLMs to retrieve relevant, up-to-date documentation on demand 9 | - Reduction in time spent correcting outdated solutions from AI tools 10 | - Streamlined workflow when working with cutting-edge or rapidly evolving technologies 11 | 12 | ## User Experience Goals 13 | - **Transparent Integration**: LLMs can seamlessly access documentation through tool calls 14 | - **Currency**: Always provides the most up-to-date documentation information 15 | - **Relevance**: Returns only the most pertinent documentation to the current task 16 | - **Efficiency**: Optimizes context usage through targeted retrieval 17 | - **Adaptability**: Works across different documentation formats and technical domains 18 | 19 | ## User Workflow 20 | 1. Developer installs TheAlmanac MCP server to extend their LLM capabilities 21 | 2. The MCP registers tools with the LLM for documentation retrieval 22 | 3. When the LLM needs documentation (e.g., for a function call or code snippet), it calls the appropriate MCP tool 23 | 4. TheAlmanac MCP retrieves documentation (scraping and storing if not already available) 24 | 5. TheAlmanac returns precisely relevant documentation sections to the LLM 25 | 6. The LLM incorporates this documentation into its response 26 | 7. The developer receives more accurate, current solutions based on up-to-date documentation 27 | 28 | ## Key Differentiators 29 | - Implements Model Context Protocol (MCP) to provide LLMs with documentation access tools 30 | - Functions as a server that LLMs can call when they need documentation 31 | - Automatically scrapes and stores documentation when needed 32 | - Intelligently retrieves only the most relevant documentation sections 33 | - Bridges the gap between LLM knowledge cutoffs and current technology state 34 | - Enables local documentation storage with an option for remote server connection 35 | 36 | ## Market Positioning 37 | TheAlmanac is positioned as an essential MCP extension for AI-assisted development workflows, enabling LLMs to access the most current documentation through direct tool calls, particularly valuable for rapidly evolving technologies and libraries released after LLM training cutoffs. 38 | 39 | ## Target Users 40 | - Software developers using AI coding assistants 41 | - Technical teams working with cutting-edge technologies 42 | - Organizations seeking to maximize the effectiveness of their AI coding tools 43 | - DevOps and platform engineers working with evolving infrastructure tools 44 | - Open source communities wanting to ensure their latest documentation is accessible to LLMs -------------------------------------------------------------------------------- /.clauderules: -------------------------------------------------------------------------------- 1 | # Claude Rules for TheAlmanac Project 2 | 3 | ## Project Understanding 4 | - TheAlmanac implements MCP (Model Context Protocol) tools for LLMs to access documentation 5 | - The system will crawl, store, and intelligently retrieve documentation 6 | - Implementation is in Python with SQLite initial storage, later vector database 7 | - Development follows distinct phases, each delivering standalone value 8 | - Both local storage and remote server options will be supported 9 | - Existing markdownCLICrawler code will be reused for the crawler component 10 | 11 | ## Phase Approach 12 | - Each phase must be treated as a standalone project with clear completion criteria 13 | - No phase should be considered "work in progress" when moving to the next phase 14 | - Testing requirements must be met for a phase to be considered complete 15 | - Each phase should deliver actual value to users 16 | 17 | ## Implementation Guidelines 18 | - Use Python for all components of the system 19 | - Adapt existing markdownCLICrawler code with minimal changes 20 | - Follow modular design with clear component separation 21 | - Prioritize testability in all architectural decisions 22 | - Consider crawler respectfulness (rate limiting, robots.txt) a critical requirement 23 | - Plan for migration from SQLite to vector database from the beginning 24 | 25 | ## User Communication Preferences 26 | - Use "plan" command to activate Plan Mode for strategic discussions 27 | - Use "act" command to activate Act Mode for implementation tasks 28 | - Regularly update Memory Bank with new developments 29 | - Maintain clear phase-by-phase progress tracking 30 | 31 | ## Development Workflow 32 | - Build and test individual components before integration 33 | - Document all significant design decisions and implementation details 34 | - Write automated tests for all functionality 35 | - Focus on crawler integration and storage system as the first priority 36 | 37 | ## Documentation Standards 38 | - Keep Memory Bank files up-to-date with latest developments 39 | - Document code with clear comments explaining purpose and approach 40 | - Update phase completion status as progress is made 41 | - Document any challenges or decisions that affect future phases 42 | 43 | ## Project Patterns 44 | - Server-based architecture exposing MCP tools to LLMs 45 | - Phased implementation with clear standalone value at each phase 46 | - Separation of crawler, storage, retrieval, and intelligence concerns 47 | - Modular components with clear interfaces for future enhancement 48 | - Adapter pattern for integrating existing crawler code 49 | 50 | ## Technical Considerations 51 | - Design SQLite schema for future migration to vector database 52 | - Ensure crawler is respectful of web resources (already implemented in existing code) 53 | - Consider security in MCP tool interface design 54 | - Test retrieval effectiveness with real-world documentation 55 | - Plan for system performance with large documentation sets 56 | 57 | ## Future Expansion Areas 58 | - Additional documentation format support 59 | - Enhanced intelligence capabilities beyond initial RAG implementation 60 | - User interface improvements beyond CLI 61 | - Community contribution management 62 | - Integration with additional LLM providers -------------------------------------------------------------------------------- /docs/uv-backup/uv_guides_integration_fastapi.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Using uv with FastAPI 3 | FastAPI is a modern, high-performance Python web framework. You can use uv to manage your FastAPI project, including installing dependencies, managing environments, running FastAPI applications, and more. 4 | Note 5 | You can view the source code for this guide in the uv-fastapi-example repository. 6 | ## Migrating an existing FastAPI project 7 | As an example, consider the sample application defined in the FastAPI documentation, structured as follows: 8 | ``` 9 | project 10 | └── app 11 | ├── __init__.py 12 | ├── main.py 13 | ├── dependencies.py 14 | ├── routers 15 | │ ├── __init__.py 16 | │ ├── items.py 17 | │ └── users.py 18 | └── internal 19 | ├── __init__.py 20 | └── admin.py 21 | 22 | ``` 23 | 24 | To use uv with this application, inside the `project` directory run: 25 | ``` 26 | $ uvinit--app 27 | 28 | ``` 29 | 30 | This creates an project with an application layout and a `pyproject.toml` file. 31 | Then, add a dependency on FastAPI: 32 | ``` 33 | $ uvaddfastapi--extrastandard 34 | 35 | ``` 36 | 37 | You should now have the following structure: 38 | ``` 39 | project 40 | ├── pyproject.toml 41 | └── app 42 | ├── __init__.py 43 | ├── main.py 44 | ├── dependencies.py 45 | ├── routers 46 | │ ├── __init__.py 47 | │ ├── items.py 48 | │ └── users.py 49 | └── internal 50 | ├── __init__.py 51 | └── admin.py 52 | 53 | ``` 54 | 55 | And the contents of the `pyproject.toml` file should look something like this: 56 | pyproject.toml``` 57 | [project] 58 | name="uv-fastapi-example" 59 | version="0.1.0" 60 | description="FastAPI project" 61 | readme="README.md" 62 | requires-python=">=3.12" 63 | dependencies=[ 64 | "fastapi[standard]", 65 | ] 66 | 67 | ``` 68 | 69 | From there, you can run the FastAPI application with: 70 | ``` 71 | $ uvrunfastapidev 72 | 73 | ``` 74 | 75 | `uv run` will automatically resolve and lock the project dependencies (i.e., create a `uv.lock` alongside the `pyproject.toml`), create a virtual environment, and run the command in that environment. 76 | Test the app by opening http://127.0.0.1:8000/?token=jessica in a web browser. 77 | ## Deployment 78 | To deploy the FastAPI application with Docker, you can use the following `Dockerfile`: 79 | Dockerfile``` 80 | FROMpython:3.12-slim 81 | 82 | # Install uv. 83 | COPY--from=ghcr.io/astral-sh/uv:latest/uv/uvx/bin/ 84 | 85 | # Copy the application into the container. 86 | COPY./app 87 | 88 | # Install the application dependencies. 89 | WORKDIR/app 90 | RUNuvsync--frozen--no-cache 91 | 92 | # Run the application. 93 | CMD["/app/.venv/bin/fastapi","run","app/main.py","--port","80","--host","0.0.0.0"] 94 | 95 | ``` 96 | 97 | Build the Docker image with: 98 | ``` 99 | $ dockerbuild-tfastapi-app. 100 | 101 | ``` 102 | 103 | Run the Docker container locally with: 104 | ``` 105 | $ dockerrun-p8000:80fastapi-app 106 | 107 | ``` 108 | 109 | Navigate to http://127.0.0.1:8000/?token=jessica in your browser to verify that the app is running correctly. 110 | Tip 111 | For more on using uv with Docker, see the Docker guide. 112 | Back to top 113 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_industry_manufacturing.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | Manufacturing solutions 5 | # Advance manufacturing with a complete, AI-powered platform 6 | By integrating AI into developer workflows, you can securely transform manufacturing operations at scale. 7 | Start a free trialContact sales 8 | ### Enhance industrial efficiency 9 | Ensure the reliable implementation of cutting-edge technologies by incorporating security practices throughout the development process. 10 | ### Move fast, safely 11 | Build at the speed of innovation and enable faster deployment by embedding AI into developer workflows. 12 | ### Reduce context switching 13 | Boost efficiency and increase creativity by enabling developers to plan, track, and build in a single, integrated, AI-powered platform. 14 | ## Logos for 3M P&G Decathlon Ford and Bolt 15 | 3M 16 | Procter and Gamble 17 | Decathlon 18 | Ford 19 | Bolt 20 | ### Drive industrial innovation 21 | Boost developer productivity and innovation with AI-powered tools, while remaining secure and compliant. 22 | Explore GitHub Copilot 23 | ![](https://images.ctfassets.net/8aevphvgewt8/2wVRwXVlNHT1y9ljsR5apI/af3eac47ceaa4d1967dd26c2ef8a0ff6/AI-1.webp) 24 | ### Secure your supply chain 25 | Minimize the risk of disruptions and data breaches by using robust security features and best practices, embedded directly into the developer workflow. 26 | Explore GitHub Advanced Security 27 | ![](https://images.ctfassets.net/8aevphvgewt8/7hyREaHfmE1bUDbxWOb3pP/2055d9ac1fe123bc3a1fcedab68ba4a0/Security-1.webp) 28 | ### Support developers with automation 29 | Transform continuous integration processes by using enterprise-ready, scalable CI/CD—now with Arm-hosted runners. 30 | Explore Arm64 on GitHub Actions 31 | ![](https://images.ctfassets.net/8aevphvgewt8/3TNCljJWvty7dks0L7rtho/1682ac8e20fe52bc3edabdae609771a1/Automation-1.webp) 32 | ### Read how Procter & Gamble streamlined the developer experience and improved developer satisfaction and security. 33 | Read the customer story 34 | ![](https://images.ctfassets.net/8aevphvgewt8/6RJ6JpV1qJ22isq9BFg3S0/13507e4fb849e228b51ab8310c6abef7/pg2.avif) 35 | “ 36 | > You don’t have to go out to a separate project management tool. You don’t have to go to a spreadsheet, or a Microsoft project, or into Jira. It’s all on GitHub. It’s made us more productive. 37 | ![](https://images.ctfassets.net/8aevphvgewt8/2tMTWbmqMOioMvIqJkRqiy/a2a172f59fdbdb07be513dc9b5e40a14/download-1.png?fm=webp&w=120&q=90) 38 | Tina Beamer3M IT manager of operations and quality 39 | ### DevOps strategies for manufacturing innovation, amplified by GitHub 40 | Trusted by 90% of the Fortune 100, GitHub helps millions of developers and companies collaborate, build, and deliver secure software faster. And with thousands of DevOps integrations, developers can build smarter from day one with the tools they know and love—or discover new ones. 41 | Start a free trialContact sales 42 | You can’t perform that action at this time. 43 | -------------------------------------------------------------------------------- /scripts/example_workflow.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """Example workflow for TheAlmanac.""" 3 | import asyncio 4 | import logging 5 | import sys 6 | from pathlib import Path 7 | 8 | # Add parent directory to path 9 | sys.path.insert(0, str(Path(__file__).parent.parent)) 10 | 11 | from almanac.crawler.adapter import DocumentationCrawler 12 | from almanac.search.text_search import DocumentationSearch 13 | from almanac.storage.filesystem import DocumentationStorage 14 | 15 | # Configure logging 16 | logging.basicConfig( 17 | level=logging.INFO, 18 | format="%(asctime)s - %(levelname)s - %(message)s" 19 | ) 20 | logger = logging.getLogger(__name__) 21 | 22 | 23 | async def example_workflow(docs_dir: str = "docs"): 24 | """Run an example workflow.""" 25 | logger.info("Starting example workflow...") 26 | 27 | # Initialize components 28 | crawler = DocumentationCrawler(docs_dir=docs_dir) 29 | storage = DocumentationStorage(docs_dir=docs_dir) 30 | search = DocumentationSearch(storage=storage) 31 | 32 | # Step 1: Add a documentation source 33 | source_name = "uv" 34 | source_url = "https://docs.astral.sh/uv/" 35 | 36 | logger.info(f"Adding documentation source: {source_name} ({source_url})") 37 | crawler.add_source(source_name, source_url) 38 | 39 | # Step 2: Download documentation 40 | logger.info(f"Downloading documentation for {source_name}...") 41 | output_dir = await crawler.download_documentation(source_name) 42 | 43 | if not output_dir: 44 | logger.error(f"Failed to download documentation for {source_name}") 45 | return 46 | 47 | logger.info(f"Documentation downloaded to {output_dir}") 48 | 49 | # Step 3: List available documents 50 | documents = storage.list_documents(source_name) 51 | logger.info(f"Available documents for {source_name}:") 52 | for doc in documents: 53 | logger.info(f" - {doc.name}") 54 | 55 | # Step 4: Search for something 56 | query = "install" 57 | logger.info(f"Searching for '{query}' in {source_name}...") 58 | results = search.basic_search(query, source_name) 59 | 60 | if not results or not results.get(source_name): 61 | logger.info(f"No results found for '{query}' in {source_name}") 62 | else: 63 | source_results = results[source_name] 64 | logger.info(f"Found {len(source_results)} results for '{query}' in {source_name}") 65 | 66 | for i, result in enumerate(source_results[:3], 1): # Show top 3 results 67 | doc = result["document"] 68 | heading = result["heading"] 69 | context = result["context"] 70 | 71 | logger.info(f"\nResult {i}: {doc}" + (f" ({heading})" if heading else "")) 72 | logger.info("---") 73 | logger.info(context) 74 | 75 | logger.info("\nExample workflow completed!") 76 | 77 | 78 | if __name__ == "__main__": 79 | import argparse 80 | 81 | parser = argparse.ArgumentParser(description="Run example workflow") 82 | parser.add_argument("--docs-dir", default="docs", help="Documentation directory") 83 | 84 | args = parser.parse_args() 85 | 86 | asyncio.run(example_workflow(args.docs_dir)) -------------------------------------------------------------------------------- /memory-bank/techContext.md: -------------------------------------------------------------------------------- 1 | # Technical Context 2 | 3 | ## Core Technologies 4 | 5 | ### Backend 6 | - **Language**: Python 7 | - **Web Scraping**: Leverage existing custom crawler from markdownCLICrawler project 8 | - **Database**: SQLite initially, with potential migration to a vector database later 9 | - **Text Processing**: NLP capabilities for parsing documentation 10 | 11 | ### Existing Crawler Code 12 | - **Location**: /Users/saharcarmel/Code/markdownCLICrawler 13 | - **Dependencies**: 14 | - crawl4ai (>=0.4.243) - Powers the web crawling functionality 15 | - pyyaml (>=6.0.1) - For configuration file handling 16 | - **Key Components**: 17 | - AsyncWebCrawler - For efficient asynchronous crawling 18 | - DefaultMarkdownGenerator - Converts HTML to clean Markdown 19 | - PruningContentFilter - Removes low-value content 20 | 21 | ### MCP Implementation 22 | - **Model Context Protocol**: Implementation of tools for LLM to call 23 | - **Server Architecture**: Python-based API server that responds to LLM tool calls 24 | - **Tool Registration**: System for registering documentation tools with LLMs 25 | 26 | ### Intelligence Layer 27 | - **Initial Approach**: Basic keyword matching and document segmentation 28 | - **Enhanced Approach**: RAG (Retrieval Augmented Generation) or similar LLM techniques 29 | - **Context Optimization**: Techniques to return only the most relevant documentation sections 30 | 31 | ### API & Integration 32 | - **MCP Interface**: Standardized interface for LLM tool calls 33 | - **Documentation API**: Python endpoints for documentation retrieval 34 | - **Cloud Connection**: Option for remote documentation server 35 | 36 | ## Development Environment 37 | - **Version Control**: Git 38 | - **Testing Framework**: Pytest 39 | - **Database Management**: SQLite tools initially, vector database tools later 40 | 41 | ## Technical Constraints 42 | - Documentation formats are not standardized across different sources 43 | - Web scraping may encounter anti-scraping protections 44 | - Custom crawler needs to handle various site structures 45 | - SQLite has limitations for scaling that will need to be addressed with vector DB 46 | - Must efficiently identify precisely relevant documentation sections 47 | 48 | ## Dependencies 49 | - MCP specification and implementation standards 50 | - crawl4ai for web crawling and parsing 51 | - SQLite for initial storage 52 | - Vector database implementation (for later phases) 53 | - LLM tool call capabilities 54 | 55 | ## Security Considerations 56 | - Secure storage of documentation 57 | - Rate limiting in custom crawler to respect website policies (implemented in existing crawler) 58 | - Secure connection to remote documentation server 59 | - Proper authentication for tool calls 60 | - Handling of potentially sensitive information in documentation 61 | 62 | ## Performance Requirements 63 | - Fast documentation retrieval from SQLite/vector database 64 | - Efficient storage utilization 65 | - Quick response times to LLM tool calls 66 | - Minimal latency for remote server connection 67 | - Precise retrieval of relevant documentation sections 68 | 69 | ## Scaling Considerations 70 | - Migration path from SQLite to vector database for larger documentation sets 71 | - Supporting multiple LLM connections 72 | - Managing documentation updates efficiently 73 | - Balancing local vs. remote storage options -------------------------------------------------------------------------------- /docs/uv-backup/uv_guides_install-python.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Installing Python 3 | If Python is already installed on your system, uv will detect and use it without configuration. However, uv can also install and manage Python versions. uv automatically installs missing Python versions as needed — you don't need to install Python to get started. 4 | ## Getting started 5 | To install the latest Python version: 6 | ``` 7 | $ uvpythoninstall 8 | 9 | ``` 10 | 11 | Note 12 | Python does not publish official distributable binaries. As such, uv uses distributions from the Astral `python-build-standalone` project. See the Python distributions documentation for more details. 13 | Once Python is installed, it will be used by `uv` commands automatically. 14 | Important 15 | When Python is installed by uv, it will not be available globally (i.e. via the `python` command). Support for this feature is in _preview_. See Installing Python executables for details. 16 | You can still use `uv run` or create and activate a virtual environment to use `python` directly. 17 | ## Installing a specific version 18 | To install a specific Python version: 19 | ``` 20 | $ uvpythoninstall3.12 21 | 22 | ``` 23 | 24 | To install multiple Python versions: 25 | ``` 26 | $ uvpythoninstall3.113.12 27 | 28 | ``` 29 | 30 | To install an alternative Python implementation, e.g., PyPy: 31 | ``` 32 | $ uvpythoninstallpypy@3.10 33 | 34 | ``` 35 | 36 | See the `python install` documentation for more details. 37 | ## Reinstalling Python 38 | To reinstall uv-managed Python versions, use `--reinstall`, e.g.: 39 | ``` 40 | $ uvpythoninstall--reinstall 41 | 42 | ``` 43 | 44 | This will reinstall all previously installed Python versions. Improvements are constantly being added to the Python distributions, so reinstalling may resolve bugs even if the Python version does not change. 45 | ## Viewing Python installations 46 | To view available and installed Python versions: 47 | ``` 48 | $ uvpythonlist 49 | 50 | ``` 51 | 52 | See the `python list` documentation for more details. 53 | ## Automatic Python downloads 54 | Python does not need to be explicitly installed to use uv. By default, uv will automatically download Python versions when they are required. For example, the following would download Python 3.12 if it was not installed: 55 | ``` 56 | $ uvxpython@3.12-c"print('hello world')" 57 | 58 | ``` 59 | 60 | Even if a specific Python version is not requested, uv will download the latest version on demand. For example, if there are no Python versions on your system, the following will install Python before creating a new virtual environment: 61 | ``` 62 | $ uvvenv 63 | 64 | ``` 65 | 66 | Tip 67 | Automatic Python downloads can be easily disabled if you want more control over when Python is downloaded. 68 | ## Using existing Python versions 69 | uv will use existing Python installations if present on your system. There is no configuration necessary for this behavior: uv will use the system Python if it satisfies the requirements of the command invocation. See the Python discovery documentation for details. 70 | To force uv to use the system Python, provide the `--no-managed-python` flag. See the Python version preference documentation for more details. 71 | ## Next steps 72 | To learn more about `uv python`, see the Python version concept page and the command reference. 73 | Or, read on to learn how to run scripts and invoke Python with uv. 74 | Back to top 75 | -------------------------------------------------------------------------------- /scripts/test_mcp_fastmcp.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """Test script for MCP FastMCP server.""" 3 | import argparse 4 | import asyncio 5 | import json 6 | import logging 7 | import sys 8 | from pathlib import Path 9 | 10 | # Add parent directory to path 11 | sys.path.insert(0, str(Path(__file__).parent.parent)) 12 | 13 | from almanac.mcp.fastmcp_server import TheAlmanacMCP 14 | 15 | # Configure logging 16 | logging.basicConfig( 17 | level=logging.INFO, 18 | format="%(asctime)s - %(levelname)s - %(message)s" 19 | ) 20 | logger = logging.getLogger(__name__) 21 | 22 | 23 | async def test_search_documentation(docs_dir: str, query: str, source_name: str = None): 24 | """Test search documentation tool.""" 25 | logger.info(f"Testing search_documentation with query: {query}") 26 | 27 | # Get the tool function directly from TheAlmanacMCP 28 | server = TheAlmanacMCP(docs_dir=docs_dir) 29 | 30 | # Find the search_documentation tool in the FastMCP instance 31 | search_tool = None 32 | for tool_name, tool_func in server.mcp.tools.items(): 33 | if tool_name == "search_documentation": 34 | search_tool = tool_func 35 | break 36 | 37 | if not search_tool: 38 | logger.error("search_documentation tool not found!") 39 | return 40 | 41 | # Call the tool function 42 | result = await search_tool(query=query, source_name=source_name) 43 | print(result) 44 | 45 | 46 | async def test_list_documentation(docs_dir: str, source_name: str = None): 47 | """Test list documentation tool.""" 48 | logger.info(f"Testing list_documentation") 49 | 50 | # Get the tool function directly from TheAlmanacMCP 51 | server = TheAlmanacMCP(docs_dir=docs_dir) 52 | 53 | # Find the list_documentation tool in the FastMCP instance 54 | list_tool = None 55 | for tool_name, tool_func in server.mcp.tools.items(): 56 | if tool_name == "list_documentation": 57 | list_tool = tool_func 58 | break 59 | 60 | if not list_tool: 61 | logger.error("list_documentation tool not found!") 62 | return 63 | 64 | # Call the tool function 65 | result = await list_tool(source_name=source_name) 66 | print(result) 67 | 68 | 69 | def main(): 70 | """Main function.""" 71 | parser = argparse.ArgumentParser(description="Test MCP FastMCP server") 72 | parser.add_argument("--docs-dir", default="docs", help="Documentation directory") 73 | 74 | subparsers = parser.add_subparsers(dest="command", help="Command to run") 75 | 76 | # Search documentation 77 | search_parser = subparsers.add_parser("search", help="Test search_documentation tool") 78 | search_parser.add_argument("query", help="Search query") 79 | search_parser.add_argument("--source", help="Source name") 80 | 81 | # List documentation 82 | list_parser = subparsers.add_parser("list", help="Test list_documentation tool") 83 | list_parser.add_argument("--source", help="Source name") 84 | 85 | args = parser.parse_args() 86 | 87 | if args.command == "search": 88 | asyncio.run(test_search_documentation(args.docs_dir, args.query, args.source)) 89 | elif args.command == "list": 90 | asyncio.run(test_list_documentation(args.docs_dir, args.source)) 91 | else: 92 | parser.print_help() 93 | 94 | 95 | if __name__ == "__main__": 96 | main() -------------------------------------------------------------------------------- /docs/uv-backup/uv_concepts_projects_layout.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Project structure and files 3 | ## The `pyproject.toml` 4 | Python project metadata is defined in a `pyproject.toml` file. uv requires this file to identify the root directory of a project. 5 | Tip 6 | `uv init` can be used to create a new project. See Creating projects for details. 7 | A minimal project definition includes a name and version: 8 | pyproject.toml``` 9 | [project] 10 | name="example" 11 | version="0.1.0" 12 | 13 | ``` 14 | 15 | Additional project metadata and configuration includes: 16 | * Python version requirement 17 | * Dependencies 18 | * Build system 19 | * Entry points (commands) 20 | 21 | 22 | ## The project environment 23 | When working on a project with uv, uv will create a virtual environment as needed. While some uv commands will create a temporary environment (e.g., `uv run --isolated`), uv also manages a persistent environment with the project and its dependencies in a `.venv` directory next to the `pyproject.toml`. It is stored inside the project to make it easy for editors to find — they need the environment to give code completions and type hints. It is not recommended to include the `.venv` directory in version control; it is automatically excluded from `git` with an internal `.gitignore` file. 24 | To run a command in the project environment, use `uv run`. Alternatively the project environment can be activated as normal for a virtual environment. 25 | When `uv run` is invoked, it will create the project environment if it does not exist yet or ensure it is up-to-date if it exists. The project environment can also be explicitly created with `uv sync`. See the locking and syncing documentation for details. 26 | It is _not_ recommended to modify the project environment manually, e.g., with `uv pip install`. For project dependencies, use `uv add` to add a package to the environment. For one-off requirements, use `uvx` or `uv run --with`. 27 | Tip 28 | If you don't want uv to manage the project environment, set `managed = false` to disable automatic locking and syncing of the project. For example: 29 | pyproject.toml``` 30 | [tool.uv] 31 | managed=false 32 | 33 | ``` 34 | 35 | ## The lockfile 36 | uv creates a `uv.lock` file next to the `pyproject.toml`. 37 | `uv.lock` is a _universal_ or _cross-platform_ lockfile that captures the packages that would be installed across all possible Python markers such as operating system, architecture, and Python version. 38 | Unlike the `pyproject.toml`, which is used to specify the broad requirements of your project, the lockfile contains the exact resolved versions that are installed in the project environment. This file should be checked into version control, allowing for consistent and reproducible installations across machines. 39 | A lockfile ensures that developers working on the project are using a consistent set of package versions. Additionally, it ensures when deploying the project as an application that the exact set of used package versions is known. 40 | The lockfile is automatically created and updated during uv invocations that use the project environment, i.e., `uv sync` and `uv run`. The lockfile may also be explicitly updated using `uv lock`. 41 | `uv.lock` is a human-readable TOML file but is managed by uv and should not be edited manually. There is no Python standard for lockfiles at this time, so the format of this file is specific to uv and not usable by other tools. 42 | Back to top 43 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_concepts_projects_run.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Running commands in projects 3 | When working on a project, it is installed into the virtual environment at `.venv`. This environment is isolated from the current shell by default, so invocations that require the project, e.g., `python -c "import example"`, will fail. Instead, use `uv run` to run commands in the project environment: 4 | ``` 5 | $ uvrunpython-c"import example" 6 | 7 | ``` 8 | 9 | When using `run`, uv will ensure that the project environment is up-to-date before running the given command. 10 | The given command can be provided by the project environment or exist outside of it, e.g.: 11 | ``` 12 | $ # Presuming the project provides `example-cli` 13 | $ uvrunexample-clifoo 14 | 15 | $ # Running a `bash` script that requires the project to be available 16 | $ uvrunbashscripts/foo.sh 17 | 18 | ``` 19 | 20 | ## Requesting additional dependencies 21 | Additional dependencies or different versions of dependencies can be requested per invocation. 22 | The `--with` option is used to include a dependency for the invocation, e.g., to request a different version of `httpx`: 23 | ``` 24 | $ uvrun--withhttpx==0.26.0python-c"import httpx; print(httpx.__version__)" 25 | 0.26.0 26 | $ uvrun--withhttpx==0.25.0python-c"import httpx; print(httpx.__version__)" 27 | 0.25.0 28 | 29 | ``` 30 | 31 | The requested version will be respected regardless of the project's requirements. For example, even if the project requires `httpx==0.24.0`, the output above would be the same. 32 | ## Running scripts 33 | Scripts that declare inline metadata are automatically executed in environments isolated from the project. See the scripts guide for more details. 34 | For example, given a script: 35 | example.py``` 36 | # /// script 37 | # dependencies = [ 38 | # "httpx", 39 | # ] 40 | # /// 41 | 42 | import httpx 43 | 44 | resp = httpx.get("https://peps.python.org/api/peps.json") 45 | data = resp.json() 46 | print([(k, v["title"]) for k, v in data.items()][:10]) 47 | 48 | ``` 49 | 50 | The invocation `uv run example.py` would run _isolated_ from the project with only the given dependencies listed. 51 | ## Legacy Windows Scripts 52 | Support is provided for legacy setuptools scripts. These types of scripts are additional files installed by setuptools in `.venv\Scripts`. 53 | Currently only legacy scripts with the `.ps1`, `.cmd`, and `.bat` extensions are supported. 54 | For example, below is an example running a Command Prompt script. 55 | ``` 56 | $ uvrun--withnuitka==2.6.7--nuitka.cmd--version 57 | 58 | ``` 59 | 60 | In addition, you don't need to specify the extension. `uv` will automatically look for files ending in `.ps1`, `.cmd`, and `.bat` in that order of execution on your behalf. 61 | ``` 62 | $ uvrun--withnuitka==2.6.7--nuitka--version 63 | 64 | ``` 65 | 66 | ## Signal handling 67 | uv does not cede control of the process to the spawned command in order to provide better error messages on failure. Consequently, uv is responsible for forwarding some signals to the child process the requested command runs in. 68 | On Unix systems, uv will forward SIGINT and SIGTERM to the child process. Since shells send SIGINT to the foreground process group on Ctrl-C, uv will only forward a SIGINT to the child process if it is seen more than once or the child process group differs from uv's. 69 | On Windows, these concepts do not apply and uv ignores Ctrl-C events, deferring handling to the child process so it can exit cleanly. 70 | Back to top 71 | -------------------------------------------------------------------------------- /tests/test_storage.py: -------------------------------------------------------------------------------- 1 | """Tests for the filesystem storage.""" 2 | import os 3 | import shutil 4 | import tempfile 5 | from pathlib import Path 6 | 7 | import pytest 8 | 9 | from almanac.storage.filesystem import DocumentationStorage 10 | 11 | 12 | @pytest.fixture 13 | def temp_docs_dir(): 14 | """Create a temporary docs directory for testing.""" 15 | temp_dir = tempfile.mkdtemp() 16 | yield temp_dir 17 | shutil.rmtree(temp_dir) 18 | 19 | 20 | @pytest.fixture 21 | def sample_docs(temp_docs_dir): 22 | """Create sample documentation for testing.""" 23 | # Create source directory 24 | source_dir = Path(temp_docs_dir) / "python" 25 | source_dir.mkdir(parents=True, exist_ok=True) 26 | 27 | # Create sample documents 28 | doc1 = source_dir / "index.md" 29 | doc1.write_text("""# Python Documentation 30 | 31 | This is a sample document for testing. 32 | 33 | ## Functions 34 | 35 | Python has many built-in functions like `print()` and `len()`. 36 | 37 | ## Classes 38 | 39 | Python supports object-oriented programming. 40 | """) 41 | 42 | doc2 = source_dir / "tutorial.md" 43 | doc2.write_text("""# Python Tutorial 44 | 45 | This is a tutorial for Python. 46 | 47 | ## Getting Started 48 | 49 | First, install Python from python.org. 50 | 51 | ## Basic Syntax 52 | 53 | Python uses indentation for blocks. 54 | """) 55 | 56 | return temp_docs_dir 57 | 58 | 59 | def test_storage_init(temp_docs_dir): 60 | """Test storage initialization.""" 61 | storage = DocumentationStorage(docs_dir=temp_docs_dir) 62 | assert storage.docs_dir == Path(temp_docs_dir) 63 | assert os.path.exists(temp_docs_dir) 64 | 65 | 66 | def test_list_sources(sample_docs): 67 | """Test listing sources.""" 68 | storage = DocumentationStorage(docs_dir=sample_docs) 69 | sources = storage.list_sources() 70 | assert "python" in sources 71 | 72 | 73 | def test_list_documents(sample_docs): 74 | """Test listing documents.""" 75 | storage = DocumentationStorage(docs_dir=sample_docs) 76 | documents = storage.list_documents("python") 77 | assert len(documents) == 2 78 | 79 | doc_names = [doc.name for doc in documents] 80 | assert "index.md" in doc_names 81 | assert "tutorial.md" in doc_names 82 | 83 | 84 | def test_get_document(sample_docs): 85 | """Test getting a document.""" 86 | storage = DocumentationStorage(docs_dir=sample_docs) 87 | 88 | # Test existing document 89 | content = storage.get_document("python", "index.md") 90 | assert content is not None 91 | assert "# Python Documentation" in content 92 | 93 | # Test non-existent document 94 | content = storage.get_document("python", "nonexistent.md") 95 | assert content is None 96 | 97 | 98 | def test_search_documents(sample_docs): 99 | """Test searching documents.""" 100 | storage = DocumentationStorage(docs_dir=sample_docs) 101 | 102 | # Test search with results 103 | results = storage.search_documents("python", "functions") 104 | assert len(results) > 0 # We might get multiple matches 105 | assert any(result["document"] == "index.md" for result in results) 106 | assert any("Python has many built-in functions" in result["context"] for result in results) 107 | 108 | # Test search with no results 109 | results = storage.search_documents("python", "nonexistent") 110 | assert len(results) == 0 -------------------------------------------------------------------------------- /docs/uv-backup/solutions.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | ![](https://images.ctfassets.net/8aevphvgewt8/2y5vMAzPdBETL4MaRatk5i/bb416271611c749165b93fdd01df8966/merge-lines.webp?w=2400&fm=jpg&fl=progressive) 5 | # AI-powered platform solutions to solve your company’s challenges 6 | GitHub empowers your team to deliver software faster and more efficiently, while maintaining robust security and compliance. 7 | Start a free trialContact sales 8 | ### Enterprises 9 | Build, scale, and deliver secure software faster with GitHub’s AI-powered developer platform. 10 | Learn more 11 | ### Teams 12 | With CI/CD, Dependabot, and the world's largest developer community, GitHub provides everything your team needs to ship secure software faster. 13 | Learn more 14 | ### Startups 15 | Go from idea to IPO in one place, complete with personalized onboarding, office hours, and tailored product guidance. 16 | Learn more 17 | ### The enterprise-grade platform that developers know and love. 18 | Learn more about GitHub Enterprise 19 | ![Stack with GitHub logo on the top layer](https://images.ctfassets.net/8aevphvgewt8/29CiGKTG31W7VVxW3MXimT/cfdab99c54f2dd057746274707fa05c9/Stack-GitHub-logo.webp) 20 | ### Healthcare 21 | By incorporating security checks into developer workflows, you can build secure communication channels between patients and providers. 22 | Learn more 23 | ### Financial Services 24 | With an AI-powered developer platform, you can build innovative financial solutions that drive economic growth. 25 | Learn more 26 | ### Manufacturing 27 | With robust CI/CD that can handle the complex needs of manufacturing, you can securely transform operations at scale. 28 | Learn more 29 | ### DevSecOps 30 | With comprehensive security tools built into the developer workflow, you can build, secure, and ship all in one place. 31 | Learn more 32 | ### DevOps 33 | Scale and deliver more secure software with GitHub's unified AI-powered developer platform. 34 | Learn more 35 | ### CI/CD 36 | Test and deploy software with simple and secure enterprise CI/CD. 37 | Learn more 38 | ## Adopted by the world's leading organizations 39 | ### 3M transforms its software toolchain to bring cutting-edge science to customers, faster. 40 | ![Tower with 3M at the top](https://images.ctfassets.net/8aevphvgewt8/4VrAcl170GPqwcaaflY1zt/0ca1a1e24a949889bc5c85482406a6f3/3M_tower.webp?fm=webp) 41 | Read story 42 | ### Philips builds and deploys digital health technology faster with innersource on GitHub. 43 | ![doctor](https://images.ctfassets.net/8aevphvgewt8/365n7ERNkjzhn9SPqfNuqJ/b3829500dfb573e878c1ede4d389e1f5/doctor-small.webp?fm=webp) 44 | Read story 45 | ### GitHub brings DevOps to life and enables streamlined developer experiences at Procter & Gamble. 46 | ![Building with 2 towers and flags](https://images.ctfassets.net/8aevphvgewt8/4iJEc5NkUQTrz8ivwmAw8B/de3104ffb1190f47c4b60074f10f71ba/pg2-1.webp?fm=webp) 47 | Read story 48 | ### Get started 49 | Trusted by 90% of the Fortune 100, GitHub helps millions of developers and companies collaborate, build, and deliver secure software faster. And with thousands of DevOps integrations, developers can build smarter from day one with the tools they know and love—or discover new ones. 50 | Start a free trialContact sales 51 | You can’t perform that action at this time. 52 | -------------------------------------------------------------------------------- /docs/uv-backup/resources_articles.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | # All Topics 5 | ## Topics 6 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 7 | ### Natural language processing (NLP) in software development 8 | Learn why natural language processing (NLP) is becoming an indispensable tool for developers. 9 | Learn more 10 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 11 | ### What are AI models? 12 | Learn how AI models help organizations identify data patterns, automate workflows, solve complex problems, forecast outcomes, and enhance decision making. 13 | Learn more 14 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 15 | ### What is a security risk assessment? 16 | Learn what a security risk assessment is, how to perform one effectively, and the key benefits of identifying and mitigating potential risks. 17 | Learn more 18 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 19 | ### What is Cross-Site Scripting (XSS) 20 | Discover how cross-site scripting (XSS) compromises web security and impacts users and organizations. Gain insights from real-world examples and learn about best practices to safeguard your applications. 21 | Learn more 22 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 23 | ### What is secret scanning? 24 | In today's digital landscape, protecting sensitive information is crucial for maintaining the integrity and security of an organization’s software systems. 25 | Learn more 26 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 27 | ### Dynamic application security testing (DAST) 28 | DAST is an AppSec method that simulates attacks to test web apps for security issues. 29 | Learn more 30 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 31 | ### What is CI/CD? 32 | Continuous Integration and Continuous Delivery/Deployment or (CI/CD) automates builds, testing, and deployment so you can ship code changes faster and reliably 33 | Learn more 34 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 35 | ### What is a DevOps engineer and what does a DevOps engineer do? 36 | A DevOps engineer enables collaboration and innovation within an organization. 37 | Learn more 38 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 39 | ### Enhancing software development with retrieval-augmented generation 40 | Learn how Retrieval Augmented Generation (RAG) improves coding, debugging, and code reviews. 41 | Learn more 42 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 43 | ### What Is Incident Response? 44 | In today’s evolving threat landscape, a robust incident response plan is essential to minimize damage, protect sensitive data, and ensure business continuity. 45 | Learn more 46 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 47 | ### What is software supply chain security? 48 | Learn how software supply chain security helps organizations protect the safety, reliability, and integrity of their software supply chains from cybersecurity threats. 49 | Learn more 50 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 51 | ### What are code repositories? 52 | Ever wonder where all that code you write actually lives? Welcome to the world of code repositories. 53 | Learn more 54 | You can’t perform that action at this time. 55 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_industry_financial-services.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | Financial services 5 | # Transform financial services with a secure, AI-powered solution 6 | By embedding AI into developer workflows, you can accelerate secure financial innovation at scale. 7 | Start a free trialContact sales 8 | ### Reduce risk 9 | Avoid data breaches and fraud by incorporating security practices throughout the development process. 10 | ### Increase speed and efficiency 11 | Enable faster development and deployment of new features and services by leaving the manual, repetitive tasks to AI. 12 | ### Streamline operations 13 | Improve efficiency and enhance developer creativity by working on a single, secure, AI-powered platform. 14 | ## Logos for Itaú Mercari Mercado Libre Stripe and Plaid 15 | Stripe 16 | Plaid 17 | Dow Jones 18 | Société Générale 19 | ### Get ahead with AI-powered innovation 20 | Stay at the forefront of technological advancements by using AI-powered tools to innovate services while remaining secure and compliant. 21 | Explore GitHub Copilot 22 | ![](https://images.ctfassets.net/8aevphvgewt8/2Bv7MCBhvh3AmQqJcXOzDH/94fc994576fde4cb2c4a68de4bf93827/AI.webp) 23 | ### Enhance regulatory compliance and security 24 | Meet regulatory standards and secure your supply chain by leveraging AI-powered compliance features and natively-embedded application security testing. 25 | Explore GitHub Advanced Security 26 | ![](https://images.ctfassets.net/8aevphvgewt8/667uH4E9obD2Y1pAsFgpSd/8bcf8082d6c0bc7a07096d04d162d2d7/Security.webp) 27 | ### Accelerate software development 28 | Automation is everything. Reduce time-to-market and improve responsiveness to customers by using enterprise-ready, scalable CI/CD. 29 | Explore GitHub Actions 30 | ![](https://images.ctfassets.net/8aevphvgewt8/1cOUJzfgvxotYU0cOMJEOf/94c3f7fb4053edd8b3f43cd3eb41aa8c/Automation.webp) 31 | ### Read how Societe Generale tripled their releases and cut development time by more than half. 32 | Read the customer story 33 | ![](https://images.ctfassets.net/8aevphvgewt8/Yb7bDbf9PXFoD31AnPGvv/beebe4e2adae829de300a764a232f3bc/sg-hero.avif) 34 | “ 35 | > We used to have other tools as well, but GitHub offers us with an all-in-one solution that provides developers a single source of truth for security notifications and code management. 36 | ![](https://images.ctfassets.net/8aevphvgewt8/5nBVvLrDM14awwu6LGS57t/044c762c1f7a4d9eec1f225bd6920e55/channels4_profile.jpg?fm=webp&w=120&q=90) 37 | David HeitzingerHead of Agile Engineering Support // Raiffeisen Bank 38 | ### DevOps strategies for financial innovation, amplified by GitHub 39 | Trusted by 90% of the Fortune 100, GitHub helps millions of developers and companies collaborate, build, and deliver secure software faster. And with thousands of DevOps integrations, developers can build smarter from day one with the tools they know and love—or discover new ones. 40 | Start a free trialContact sales 41 | ### Find the right DevOps platform 42 | Narrow your search with the 2024 Gartner® Magic Quadrant™ for DevOps Platforms report. 43 | Get the Gartner report 44 | ### What is DevOps? 45 | By bringing people, processes, and products together, DevOps enables development teams to continuously deliver value. 46 | Learn more about DevOps 47 | ### Discover innersource 48 | This practice empowers developers to save time and energy by bringing methodologies from open source into their internal development. 49 | Read more on Innersouce 50 | You can’t perform that action at this time. 51 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_pip_packages.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Managing packages 3 | ## Installing a package 4 | To install a package into the virtual environment, e.g., Flask: 5 | ``` 6 | $ uvpipinstallflask 7 | 8 | ``` 9 | 10 | To install a package with optional dependencies enabled, e.g., Flask with the "dotenv" extra: 11 | ``` 12 | $ uvpipinstall"flask[dotenv]" 13 | 14 | ``` 15 | 16 | To install multiple packages, e.g., Flask and Ruff: 17 | ``` 18 | $ uvpipinstallflaskruff 19 | 20 | ``` 21 | 22 | To install a package with a constraint, e.g., Ruff v0.2.0 or newer: 23 | ``` 24 | $ uvpipinstall'ruff>=0.2.0' 25 | 26 | ``` 27 | 28 | To install a package at a specific version, e.g., Ruff v0.3.0: 29 | ``` 30 | $ uvpipinstall'ruff==0.3.0' 31 | 32 | ``` 33 | 34 | To install a package from the disk: 35 | ``` 36 | $ uvpipinstall"ruff @ ./projects/ruff" 37 | 38 | ``` 39 | 40 | To install a package from GitHub: 41 | ``` 42 | $ uvpipinstall"git+https://github.com/astral-sh/ruff" 43 | 44 | ``` 45 | 46 | To install a package from GitHub at a specific reference: 47 | ``` 48 | $ # Install a tag 49 | $ uvpipinstall"git+https://github.com/astral-sh/ruff@v0.2.0" 50 | 51 | $ # Install a commit 52 | $ uvpipinstall"git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d" 53 | 54 | $ # Install a branch 55 | $ uvpipinstall"git+https://github.com/astral-sh/ruff@main" 56 | 57 | ``` 58 | 59 | See the Git authentication documentation for installation from a private repository. 60 | ## Editable packages 61 | Editable packages do not need to be reinstalled for changes to their source code to be active. 62 | To install the current project as an editable package 63 | ``` 64 | $ uvpipinstall-e. 65 | 66 | ``` 67 | 68 | To install a project in another directory as an editable package: 69 | ``` 70 | $ uvpipinstall-e"ruff @ ./project/ruff" 71 | 72 | ``` 73 | 74 | ## Installing packages from files 75 | Multiple packages can be installed at once from standard file formats. 76 | Install from a `requirements.txt` file: 77 | ``` 78 | $ uvpipinstall-rrequirements.txt 79 | 80 | ``` 81 | 82 | See the `uv pip compile` documentation for more information on `requirements.txt` files. 83 | Install from a `pyproject.toml` file: 84 | ``` 85 | $ uvpipinstall-rpyproject.toml 86 | 87 | ``` 88 | 89 | Install from a `pyproject.toml` file with optional dependencies enabled, e.g., the "foo" extra: 90 | ``` 91 | $ uvpipinstall-rpyproject.toml--extrafoo 92 | 93 | ``` 94 | 95 | Install from a `pyproject.toml` file with all optional dependencies enabled: 96 | ``` 97 | $ uvpipinstall-rpyproject.toml--all-extras 98 | 99 | ``` 100 | 101 | To install dependency groups in the current project directory's `pyproject.toml`, for example the group `foo`: 102 | ``` 103 | $ uvpipinstall--groupfoo 104 | 105 | ``` 106 | 107 | To specify the project directory where groups should be sourced from: 108 | ``` 109 | $ uvpipinstall--projectsome/path/--groupfoo--groupbar 110 | 111 | ``` 112 | 113 | Alternatively, you can specify a path to a `pyproject.toml` for each group: 114 | ``` 115 | $ uvpipinstall--groupsome/path/pyproject.toml:foo--groupother/pyproject.toml:bar 116 | 117 | ``` 118 | 119 | Note 120 | As in pip, `--group` flags do not apply to other sources specified with flags like `-r` or -e`. For instance,`uv pip install -r some/path/pyproject.toml --group foo`sources`foo`from`./pyproject.toml`and **not**`some/path/pyproject.toml`. 121 | ## Uninstalling a package 122 | To uninstall a package, e.g., Flask: 123 | ``` 124 | $ uvpipuninstallflask 125 | 126 | ``` 127 | 128 | To uninstall multiple packages, e.g., Flask and Ruff: 129 | ``` 130 | $ uvpipuninstallflaskruff 131 | 132 | ``` 133 | 134 | Back to top 135 | -------------------------------------------------------------------------------- /almanac.egg-info/PKG-INFO: -------------------------------------------------------------------------------- 1 | Metadata-Version: 2.4 2 | Name: almanac 3 | Version: 0.1.0 4 | Summary: Documentation assistant leveraging Model Context Protocol 5 | License: MIT 6 | Requires-Python: >=3.10 7 | Description-Content-Type: text/markdown 8 | Requires-Dist: click>=8.0.0 9 | Requires-Dist: pyyaml>=6.0.0 10 | Requires-Dist: crawl4ai>=0.4.243 11 | Requires-Dist: mcp[cli]>=1.5.0 12 | Requires-Dist: httpx>=0.28.1 13 | Provides-Extra: dev 14 | Requires-Dist: pytest>=7.0.0; extra == "dev" 15 | Requires-Dist: black>=23.0.0; extra == "dev" 16 | Requires-Dist: isort>=5.0.0; extra == "dev" 17 | 18 | # TheAlmanac 19 | 20 | A documentation assistant leveraging Model Context Protocol (MCP) to help programmers access the most up-to-date and relevant information from API and software documentation. 21 | 22 | ## Features 23 | 24 | - **Documentation Crawler**: Automatically download and store documentation locally 25 | - **Simple Search**: Find relevant documentation sections quickly 26 | - **MCP Integration**: Provide LLMs with tools to access documentation 27 | - **File-based Storage**: Efficiently organize documentation in a simple file structure 28 | - **MCP Server**: HTTP server for LLM tool access 29 | 30 | ## Installation 31 | 32 | ```bash 33 | # Clone the repository 34 | git clone https://github.com/yourusername/TheAlmanac.git 35 | cd TheAlmanac 36 | 37 | # Install dependencies with UV 38 | uv pip install -e . 39 | ``` 40 | 41 | ## Usage 42 | 43 | ### Managing Documentation Sources 44 | 45 | ```bash 46 | # Add a documentation source 47 | almanac add python https://docs.python.org/3/ 48 | 49 | # List all documentation sources 50 | almanac list 51 | 52 | # Download documentation 53 | almanac download python 54 | 55 | # Remove a documentation source 56 | almanac remove python 57 | ``` 58 | 59 | ### Searching Documentation 60 | 61 | ```bash 62 | # Search all documentation 63 | almanac search "context manager" 64 | 65 | # Search a specific source 66 | almanac search "context manager" --source python 67 | 68 | # Search with more context 69 | almanac search "context manager" --context-lines 5 70 | ``` 71 | 72 | ### Running the MCP Server 73 | 74 | ```bash 75 | # Start the MCP server 76 | almanac serve 77 | 78 | # Start on a specific host and port 79 | almanac serve --host 0.0.0.0 --port 9000 80 | ``` 81 | 82 | ## MCP Tools 83 | 84 | TheAlmanac provides the following MCP tools: 85 | 86 | 1. **search_documentation**: Search for relevant documentation 87 | 2. **get_documentation**: Get a specific document or section 88 | 3. **download_documentation**: Download a new documentation source 89 | 4. **list_documentation**: List available documentation sources 90 | 91 | ## Example Scripts 92 | 93 | The `scripts` directory contains example scripts for testing and demonstrating TheAlmanac: 94 | 95 | - `test_mcp_tools.py`: Directly test MCP tools 96 | - `test_mcp_server.py`: Test the MCP server with HTTP requests 97 | - `example_workflow.py`: Run a complete workflow example 98 | 99 | ### Example MCP Tool Usage 100 | 101 | ```bash 102 | # Test the search tool 103 | ./scripts/test_mcp_tools.py search "installation" 104 | 105 | # Test getting a specific document 106 | ./scripts/test_mcp_tools.py get python index.md 107 | 108 | # Test the complete workflow 109 | ./scripts/example_workflow.py 110 | ``` 111 | 112 | ## Development 113 | 114 | ```bash 115 | # Install development dependencies 116 | uv pip install -e ".[dev]" 117 | 118 | # Run tests 119 | uv run pytest 120 | ``` 121 | 122 | ## Adding Dependencies 123 | 124 | ```bash 125 | # Add a production dependency 126 | uv add package_name 127 | 128 | # Add a development dependency 129 | uv add --dev package_name 130 | ``` 131 | 132 | ## License 133 | 134 | MIT 135 | -------------------------------------------------------------------------------- /docs/mcp_docs/docs_concepts_roots.md: -------------------------------------------------------------------------------- 1 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 2 | Search... 3 | ⌘K 4 | * Python SDK 5 | * TypeScript SDK 6 | * Java SDK 7 | * Kotlin SDK 8 | * Specification 9 | ##### Get Started 10 | * Introduction 11 | * Quickstart 12 | * Example Servers 13 | * Example Clients 14 | 15 | 16 | ##### Tutorials 17 | * Building MCP with LLMs 18 | * Debugging 19 | * Inspector 20 | 21 | 22 | ##### Concepts 23 | * Core architecture 24 | * Resources 25 | * Prompts 26 | * Tools 27 | * Sampling 28 | * Roots 29 | * Transports 30 | 31 | 32 | ##### Development 33 | * What's New 34 | * Roadmap 35 | * Contributing 36 | 37 | 38 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 39 | Search... 40 | ⌘K 41 | Search... 42 | Navigation 43 | Concepts 44 | Roots 45 | DocumentationSDKs 46 | DocumentationSDKs 47 | * GitHub 48 | Roots are a concept in MCP that define the boundaries where servers can operate. They provide a way for clients to inform servers about relevant resources and their locations. 49 | ## 50 | ​ 51 | What are Roots? 52 | A root is a URI that a client suggests a server should focus on. When a client connects to a server, it declares which roots the server should work with. While primarily used for filesystem paths, roots can be any valid URI including HTTP URLs. 53 | For example, roots could be: 54 | Copy 55 | ``` 56 | file:///home/user/projects/myapp 57 | https://api.example.com/v1 58 | 59 | ``` 60 | 61 | ## 62 | ​ 63 | Why Use Roots? 64 | Roots serve several important purposes: 65 | 1. **Guidance** : They inform servers about relevant resources and locations 66 | 2. **Clarity** : Roots make it clear which resources are part of your workspace 67 | 3. **Organization** : Multiple roots let you work with different resources simultaneously 68 | 69 | 70 | ## 71 | ​ 72 | How Roots Work 73 | When a client supports roots, it: 74 | 1. Declares the `roots` capability during connection 75 | 2. Provides a list of suggested roots to the server 76 | 3. Notifies the server when roots change (if supported) 77 | 78 | 79 | While roots are informational and not strictly enforcing, servers should: 80 | 1. Respect the provided roots 81 | 2. Use root URIs to locate and access resources 82 | 3. Prioritize operations within root boundaries 83 | 84 | 85 | ## 86 | ​ 87 | Common Use Cases 88 | Roots are commonly used to define: 89 | * Project directories 90 | * Repository locations 91 | * API endpoints 92 | * Configuration locations 93 | * Resource boundaries 94 | 95 | 96 | ## 97 | ​ 98 | Best Practices 99 | When working with roots: 100 | 1. Only suggest necessary resources 101 | 2. Use clear, descriptive names for roots 102 | 3. Monitor root accessibility 103 | 4. Handle root changes gracefully 104 | 105 | 106 | ## 107 | ​ 108 | Example 109 | Here’s how a typical MCP client might expose roots: 110 | Copy 111 | ``` 112 | { 113 | "roots": [ 114 | { 115 | "uri": "file:///home/user/projects/frontend", 116 | "name": "Frontend Repository" 117 | }, 118 | { 119 | "uri": "https://api.example.com/v1", 120 | "name": "API Endpoint" 121 | } 122 | ] 123 | } 124 | 125 | ``` 126 | 127 | This configuration suggests the server focus on both a local repository and an API endpoint while keeping them logically separated. 128 | Was this page helpful? 129 | YesNo 130 | SamplingTransports 131 | On this page 132 | * What are Roots? 133 | * Why Use Roots? 134 | * How Roots Work 135 | * Common Use Cases 136 | * Best Practices 137 | * Example 138 | 139 | 140 | -------------------------------------------------------------------------------- /docs/uv-backup/resources_articles_security.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | # Security 5 | ## Topics 6 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 7 | ### What is a security risk assessment? 8 | Learn what a security risk assessment is, how to perform one effectively, and the key benefits of identifying and mitigating potential risks. 9 | Learn more 10 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 11 | ### What is Cross-Site Scripting (XSS) 12 | Discover how cross-site scripting (XSS) compromises web security and impacts users and organizations. Gain insights from real-world examples and learn about best practices to safeguard your applications. 13 | Learn more 14 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 15 | ### What is secret scanning? 16 | In today's digital landscape, protecting sensitive information is crucial for maintaining the integrity and security of an organization’s software systems. 17 | Learn more 18 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 19 | ### Dynamic application security testing (DAST) 20 | DAST is an AppSec method that simulates attacks to test web apps for security issues. 21 | Learn more 22 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 23 | ### What Is Incident Response? 24 | In today’s evolving threat landscape, a robust incident response plan is essential to minimize damage, protect sensitive data, and ensure business continuity. 25 | Learn more 26 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 27 | ### What is software supply chain security? 28 | Learn how software supply chain security helps organizations protect the safety, reliability, and integrity of their software supply chains from cybersecurity threats. 29 | Learn more 30 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 31 | ### What is shift left testing? 32 | Explore the benefits of shift left in software development, like early testing and efficient scanning strategies within the software development lifecycle. 33 | Learn more 34 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 35 | ### What is software composition analysis (SCA)? 36 | Software composition analysis (SCA) helps developers identify and manage security vulnerabilities in open source software, leading to more compliant, better quality code. 37 | Learn more 38 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 39 | ### What is security testing? 40 | Learn about security testing with our guide to security testing types, tools, and scanning methods, and best practices and trends for greater software security. 41 | Learn more 42 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 43 | ### What is vulnerability scanning? 44 | Discover the importance of vulnerability scanning in software development. Learn about vulnerability assessment, analysis, mitigation, and scanning tools. 45 | Learn more 46 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 47 | ### What is threat modeling? 48 | Threat modeling is a structured process that identifies security threats across systems during the design and planning phases of software production. 49 | Learn more 50 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 51 | ### What is fuzzing and fuzz testing? 52 | Discover vulnerabilities and enhance software security with fuzzing. Learn techniques, tools, and best practices for fuzz testing in software development. 53 | Learn more 54 | You can’t perform that action at this time. 55 | -------------------------------------------------------------------------------- /docs/uv-backup/resources_articles_software-development.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | # Software Development 5 | ## Topics 6 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 7 | ### What are code repositories? 8 | Ever wonder where all that code you write actually lives? Welcome to the world of code repositories. 9 | Learn more 10 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 11 | ### What is the SDLC? 12 | Learn about the software development lifecycle (SDLC) and gain valuable insights into its essential phases, methodologies, and best practices. Enhance your understanding of this crucial process to drive successful software development projects. 13 | Learn more 14 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 15 | ### What is cloud native? 16 | Cloud native is an approach to building and running scalable applications in dynamic environments like public, private, or hybrid clouds, using containers, microservices, and DevOps practices. 17 | Learn more 18 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 19 | ### What is Platform engineering? 20 | Learn what platform engineering is and how it empowers developers by creating internal developer platforms, improving workflows, and reducing operational bottlenecks. Explore the benefits for developers and IT managers alike. 21 | Learn more 22 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 23 | ### How to accelerate innovation with innersource 24 | Organizations around the world are accelerating their development cycles and tapping into new wells of innovation within their companies through "innersource" projects that share code and resources internally, enabling cross-team collaboration and contributions. 25 | Learn more 26 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 27 | ### What is Open Source Software (OSS)? 28 | Get an overview of open source software (OSS) with this guide—and explore tips for getting started. 29 | Learn more 30 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 31 | ### An introduction to innersource 32 | Organizations worldwide are incorporating open source methodologies into the way they build and ship their own software. 33 | Learn more 34 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 35 | ### What is software development? 36 | Explore software development basics including tools, security, steps, and impact on industries. 37 | Learn more 38 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 39 | ### What is Version Control? 40 | Learn how version control systems and software help track changes, support collaboration, and ensure code integrity throughout the development process. 41 | Learn more 42 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 43 | ### Tools and techniques for effective code documentation 44 | Learn about code documentation and why it’s essential for delivering quality software. 45 | Learn more 46 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 47 | ### What is software architecture? 48 | Learn how software architecture helps developers build scalable, efficient systems using best practices, key components, and common styles and patterns. 49 | Learn more 50 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 51 | ### What is a programming language? 52 | A programming language is a set of instructions that enables humans to communicate commands to a computer in software development. 53 | Learn more 54 | You can’t perform that action at this time. 55 | -------------------------------------------------------------------------------- /docs/uv-backup/resources_articles_devops.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | # DevOps 5 | ## Topics 6 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 7 | ### What is CI/CD? 8 | Continuous Integration and Continuous Delivery/Deployment or (CI/CD) automates builds, testing, and deployment so you can ship code changes faster and reliably 9 | Learn more 10 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 11 | ### What is a DevOps engineer and what does a DevOps engineer do? 12 | A DevOps engineer enables collaboration and innovation within an organization. 13 | Learn more 14 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 15 | ### What is Continuous Deployment? 16 | Continuous deployment (CD) is a process that uses automated testing to validate if changes to a codebase are secure, correct, and stable for deployment to a production environment. 17 | Learn more 18 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 19 | ### What is the DevOps Model? Exploring foundational practices in DevOps 20 | GitHub provides the tools required to be a mature DevOps organization. Discover the DevOps model that separates successful DevOps teams from those that fail. 21 | Learn more 22 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 23 | ### What is DevSecOps? 24 | DevSecOps combines development, security, and operations to automate security integration across all phases of the software development lifecycle (SDLC). 25 | Learn more 26 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 27 | ### What is containerization? 28 | Containers enable DevOps developers and system administrators to build, test, deploy, and maintain applications quickly, securely, and efficiently. 29 | Learn more 30 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 31 | ### What is DevOps automation? 32 | DevOps automation is a modern approach to software development that uses tools and processes to automate tasks and streamline workflows. 33 | Learn more 34 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 35 | ### What is agile methodology? 36 | Learn what agile is, its benefits, why it’s so popular, and how you can apply it in software development and other kinds of work. 37 | Learn more 38 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 39 | ### What is a DevOps pipeline? A complete guide 40 | Learn how to transform your organization and deliver software faster by combining processes, tooling, and automation in a DevOps Pipeline. 41 | Learn more 42 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 43 | ### What is DevOps? 44 | DevOps is a set of practices, methodologies, and tools that optimize software application delivery by integrating software development and IT operations processes. 45 | Learn more 46 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 47 | ### DevOps monitoring tools: Automating your DevOps monitoring processes 48 | Use GitHub as your approach to developing, testing, and deploying applications through comprehensive and real-time monitoring systems. Workflows are the foundation of automation and DevOps, and monitoring is the bedrock. 49 | Learn more 50 | ![](https://github.com/images/modules/site/contentful/default/md.webp) 51 | ### The fundamentals of continuous integration in DevOps 52 | Continuous Integration (CI) is a practice allowing developers to integrate code into a shared repository regularly. Get to know the fundamentals of what makes this process successful. 53 | Learn more 54 | You can’t perform that action at this time. 55 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_use-case_devsecops.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | GitHub DevSecOps 5 | # The AI-powered DevSecOps platform 6 | With comprehensive security tools built into the developer workflow, you can build, secure, and ship all in one place. 7 | Contact salesRequest a demo 8 | ![Chart displaying decreasing security incidents and highlighted code with a suggested AI fix.](https://images.ctfassets.net/8aevphvgewt8/bOTn7PNGlUzb4Vra2ZNXI/59c1667fb4ec2229aba2050de9b179f0/section-security-illo.webp?fm=webp) 9 | ### Code scanning 10 | Find and fix security issues before production with static application security testing (SAST). 11 | ### Secret scanning 12 | Hunt, revoke, and prevent leaked secrets with automatic push protection. 13 | ### Supply chain security 14 | Keep vulnerable dependencies out of your applications with software composition analysis (SCA). 15 | ## Logos for EY Mercado Libre 3M KPMG TELUS 16 | Ernst and Young 17 | Mercado Libre 18 | 3M 19 | KPMG 20 | Telus 21 | ### Give AI the heavy lifting 22 | Organizations struggle to fix their backlog of vulnerabilities, despite the risks. Coming next, security managers can burn down years of security debt in one simple sprint. 23 | Discover GitHub Copilot 24 | ![](https://images.ctfassets.net/8aevphvgewt8/6gbXLvWV2SKHPcKFcPcUJ1/68ff2a5381da67968a98b387f588563e/ai-suggested-fix2.webp) 25 | ### Found means fixed 26 | Don’t just find vulnerable code, fix it. GitHub Advanced Security flags problems and suggests AI-powered solutions, freeing teams to ship more secure software faster. 27 | Explore AI-powered security 28 | ![](https://images.ctfassets.net/8aevphvgewt8/2HTQXiXvkVKJz4SMuntu3l/6925935829f9e4cb1432556a40da95ea/ai-suggested-fix.webp) 29 | ### Pump your team’s security prowess 30 | Developers aren’t security professionals. With GitHub Advanced Security, you can offload the technical complexity and give them the freedom to build and ship great software. 31 | Discover code scanning autofix 32 | ![](https://images.ctfassets.net/8aevphvgewt8/2yTbRI9UPgLLRTewsJL8dG/a2230f0c55eec37f16be203f18a0e515/codeql-warning.webp) 33 | ### Your workflows, your way 34 | With support for more than 17,000 app integrations, GitHub Advanced Security accommodates your team’s tooling preferences. 35 | Explore GitHub Marketplace 36 | ![](https://images.ctfassets.net/8aevphvgewt8/35MGk5wBo8n5z6Ut7THgIq/de520feaf2b590da2ddf5bfb03605a9c/pyyaml-validation.webp) 37 | ### 7xfaster vulnerabilities fixes 38 | ### 2.4fewer false positives than the industry standard 39 | ### 20Mrepositories that have enabled secret scanning 40 | “ 41 | > We prefer to have security that leverages what developers are already using rather than trying to force them to use some other tool. 42 | ![Emilio Escobar avatar](https://images.ctfassets.net/8aevphvgewt8/6w7VtFNpK3sMJ8xnCiBCE/cab41b669b94ce723462f269b2c6dae0/Emilio-Escobar-Datadog-thumbnail_1__1_.png?fm=webp&w=120&q=90)Emilio EscobarChief Information Security Officer @ Datadog 43 | ### Application security made simpler 44 | Eliminate toolchain cost and complexity with native security tools for GitHub Enterprise and Azure DevOps customers. 45 | Start a free trialContact sales 46 | ### Additional resources 47 | ### DevSecOps explained 48 | Explore how DevSecOps builds on the ideas of DevOps by applying security practices throughout the SDLC. 49 | Learn more 50 | ### Meet the companies who build with unified DevSecOps 51 | Leading organizations choose GitHub to plan, build, secure, and ship software. 52 | Read customer stories 53 | ### Discover how AI is changing the security landscape 54 | From prevention to remediation, see how AI can help fix issues instantly. 55 | Watch webinar 56 | You can’t perform that action at this time. 57 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_use-case_devops.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | GitHub DevOps 5 | # The unified platform for your DevOps lifecycle 6 | Build, scale, and deliver more secure software with GitHub's unified AI-powered developer platform. 7 | Start a free trialContact sales 8 | ![Tests with checkmarks beside each test title and an activated merge pull request button](https://images.ctfassets.net/8aevphvgewt8/6cuxKTqIN1l0NMxSNlx15F/7d746be47686a08fbc09219bc63df0e5/Hero2.webp?fm=webp) 9 | ### Increase collaboration 10 | Get the tools you need to facilitate collaboration among teams. 11 | ### Eliminate barriers 12 | Harness the power of AI-powered coding to empower developer creativity and innovation. 13 | ### Reduce context switching 14 | Boost productivity with a single, integrated developer platform with powerful native tools to keep developers in the flow. 15 | ## Logos for Ford, Shopify, NASA, Vercel, and Spotify 16 | Shopify 17 | Ernst and Young 18 | Vodafone 19 | Adobe 20 | Ford 21 | ### Drive innovation with AI-powered developer tools 22 | AI-driven code suggestions enhances job satisfaction and focus for 60-75% of developers, reducing frustration and enabling more rewarding work. 23 | Explore GitHub Copilot 24 | ![Copilot making a code suggestion](https://images.ctfassets.net/8aevphvgewt8/eYhy9pDRGfRYNkXPU5qyP/0b0ce6489bebfebcc9948c15d141df85/AI2.webp) 25 | ### Built-in security 26 | Manage the SDLC with automated security tools. Find and fix vulnerabilities quickly and efficiently with security checks integrated into every step of the developer's workflow. 27 | Explore GitHub Advanced Security 28 | ![Code scanning results displaying a warning and a comment urging it to be fixed](https://images.ctfassets.net/8aevphvgewt8/K315Nmz6kmpa5aKcHmBh5/1a1a76763d1a374b691a3d450410b52a/Security2.webp) 29 | ### Streamline team collaboration 30 | Help developers and operations teams more regularly communicate and provide feedback about timelines and goals so everyone is responsible for the project’s success. 31 | Explore collaboration tools 32 | ![Project board displaying issues in prototype and beta categories](https://images.ctfassets.net/8aevphvgewt8/31ACby2yGhv2oCtr3JjQ2g/ed532822e21654463802e84bbc456266/Collaboration.webp) 33 | ### 88%of developers experience increased productivity 34 | ### 75%reduced time spent managing tools 35 | ### 1minset-up time for largest repo with GitHub Codespaces 36 | Gartner 37 | Build and innovate with a leader in the Gartner® Magic Quadrant™ for DevOps Platforms 38 | Read the report 39 | “ 40 | > The availability of out-of-the-box integrations with our existing tooling is a big part of GitHub’s appeal. GitHub really helps bring DevOps to life. 41 | Danilo SuntalManufacturing Data Flow Product and Platform, P&G 42 | ### DevOps strategies, amplified by GitHub tools 43 | Trusted by 90% of the Fortune 100, GitHub helps millions of developers and companies collaborate, build, and deliver secure software faster. And with thousands of DevOps integrations, developers can build smarter from day one with the tools you know and love—or discover new ones. 44 | Start a free trialContact sales 45 | ### Additional resources 46 | ### Find the right DevOps platform 47 | Narrow your search with the 2024 Gartner® Magic Quadrant™ for DevOps Platforms report. 48 | Get the Gartner report 49 | ### What is DevOps? 50 | By bringing people, processes, and products together, DevOps enables development teams to continuously deliver value. 51 | Learn more about DevOps 52 | ### Discover innersource 53 | This practice empowers developers to save time and energy by bringing methodologies from open source into their internal development. 54 | Read more on Innersouce 55 | You can’t perform that action at this time. 56 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_industry_government.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | Government solutions 5 | # Empowering government agencies with secure, collaborative software development 6 | With seamless collaboration and robust compliance, GitHub helps government agencies build and innovate securely on a single, AI-powered platform. 7 | Start a free trialContact sales 8 | ### Secure and compliant development 9 | With FedRAMP authorization and industry-leading security features, GitHub meets the highest standards of compliance and protection. 10 | ### Efficient collaboration across teams 11 | GitHub’s collaborative platform enables seamless code sharing, review, and feedback within your agency or with external partners. 12 | ### Flexible deployment options 13 | No matter where you need to host, GitHub Enterprise offers flexible deployment options to meet your agency’s unique operational requirements. 14 | ### Protect sensitive data 15 | Help keep your agency’s code secure with built-in vulnerability scanning, secret detection, and compliance monitoring, all seamlessly integrated into your development workflow.. 16 | Explore GitHub Advanced Security 17 | ![](https://images.ctfassets.net/8aevphvgewt8/2Bv7MCBhvh3AmQqJcXOzDH/94fc994576fde4cb2c4a68de4bf93827/AI.webp) 18 | ### Accelerate development with AI-powered assistance 19 | Whether drafting complex algorithms or automating tasks, GitHub Copilot empowers your agency to deliver mission-critical software with speed and precision. 20 | Explore GitHub Copilot 21 | ![](https://images.ctfassets.net/8aevphvgewt8/4pufdRqmUtEHxCRy4SbGq6/566eeeb0beee0f3b8c92fb3831d2290d/Security-2.webp) 22 | ### Automated, secure CI/CD 23 | With customizable workflows and integrations, your agency can streamline operations and ensure consistent, high-quality code delivery. 24 | Explore GitHub Actions 25 | ![Test passing connecting to 3 steps that are in progress](https://images.ctfassets.net/8aevphvgewt8/7JldMWj69GEj43gx9cIf5K/4d53dbc663417142a5dd826c79d4215f/Automation-2.webp) 26 | ### Learn how the VA modernizes its approach to make healthcare more accessible to millions of veterans. 27 | Read the customer story 28 | ![Sign for "Department of Vetrans Affairs"](https://images.ctfassets.net/8aevphvgewt8/4OiTTi1Nn0OdNoOkUYgUvg/2f69c981a87839aed54051cc8fde55e7/va-sign.webp) 29 | “ 30 | > We reduced our deployment time significantly. To deliver quickly, using GitHub and Azure DevOps for our DevSecOps process, CI/CD, infrastructure, code, and automation was the key. 31 | ![California Department of Technology logo](https://images.ctfassets.net/8aevphvgewt8/T2A74PzXK3NbI0giIjV7L/751e2a001a4cb0d834b7b3aeee2b7b09/California_Department_of_Technology.webp?fm=webp&w=120&q=90) 32 | Shamal SiwanLead DevOps Engineer/Solutions Architect // California Department of Technology 33 | ### DevOps strategies for government agencies, amplified by GitHub 34 | Trusted by 90% of the Fortune 100, GitHub helps millions of developers and companies collaborate, build, and deliver secure software faster. And with thousands of DevOps integrations, developers can build smarter with the tools they know from day one—or discover new ones. 35 | Contact salesStart a free enterprise trial 36 | ### Additional resources 37 | ### Find the right DevOps platform 38 | Narrow your search with the 2024 Gartner® Magic Quadrant™ for DevOps Platforms report. 39 | Get the Gartner report 40 | ### What is DevOps? 41 | By bringing people, processes, and products together, DevOps enables development teams to continuously deliver value. 42 | Learn more about DevOps 43 | ### Discover innersource 44 | This practice empowers developers to save time and energy by bringing methodologies from open source into their internal development. 45 | Read more on Innersouce 46 | You can’t perform that action at this time. 47 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_executive-insights.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | Solutions 5 | Enterprise Content 6 | # Executive insights, curated just for you 7 | ### How Thomson Reuters successfully adopted AI 8 | Thomson Reuters began their AI journey in 2022. Engineering leaders realized that what started as industry buzz was an opportunity to foster engineering excellence within the company–and GitHub Copilot could be just the thing to accelerate their operations. 9 | Learn more 10 | ### March ‘25 enterprise roundup 11 | To help you stay ahead, our Enterprise Advocacy team has curated this monthly roundup—bringing you a concise, enterprise-focused summary of the most important updates you might have missed. 12 | Learn more 13 | ### Creating space for developer creativity in high-scale organizations 14 | How do we ensure our developers can maintain the ability to innovate and experiment while operating within the constraints of a larger organization? 15 | Learn more 16 | ### Evolving GitHub Advanced Security: Greater flexibility, easier to access 17 | Starting April 1, 2025, GitHub Advanced Security (GHAS) will be unbundled and available as two standalone security products: GitHub Secret Protection and GitHub Code Security. 18 | Learn more 19 | ### Lessons from Wayfair's enterprise scale migration 20 | Wayfair’s move to GitHub Cloud was a masterclass in change management. Learn how they migrated 15,000 repositories and paved the way for innovation and cost efficiency. 21 | Learn more 22 | ### Essential GitHub Copilot resources for enterprise teams 23 | From initial setup to advanced features, this guide will walk you through the essential resources to make your Copilot implementation successful. 24 | Learn more 25 | ### Measuring the impact of GitHub Copilot 26 | Many enterprises quite reasonably ask, “How do I know Copilot is conferring these benefits for my team?” To answer that question, this guide will walk you through a framework for evaluating impact across four stages. 27 | Learn more 28 | ### The art of engineering team focus: less is more 29 | Guiding engineering teams to prioritize fewer tasks, limit parallel work, and leave space for unforeseen needs not only boosts productivity, but also fosters more consistent, high-quality work. 30 | Learn more 31 | ### Why developer satisfaction is your best productivity metric 32 | Learn how prioritizing developer satisfaction can drive better code quality, foster innovation, and improve team retention, ultimately boosting engineering productivity. 33 | Learn more 34 | ## Related solutions 35 | ### Carlsberg accelerates innovation with Copilot 36 | Carlsberg unified its development process and bolstered its security using GitHub Advanced Security, while the integration of Copilot enabled efficient coding practices and minimized the need for context-switching. 37 | Learn more 38 | ### Accenture cuts technical debt with GitHub Advanced Security and Copilot 39 | Accenture leverages GitHub Copilot and Advanced Security to reduce technical debt, driving faster project delivery and improved code quality. 40 | Learn more 41 | ### EY Scales Developer Efficiency with GitHub Copilot and Codespaces 42 | EY built integrations between GitHub and Microsoft Azure DevOps, so it could tap into the power of GitHub's cohesive developer platform for security, automation, and AI. 43 | Learn more 44 | ### 90%of Fortune 100 choose GitHub 45 | ### 433%ROI with GitHub Enterprise 46 | ### 77,000organizations use GitHub Copilot 47 | ### 75%reduced time spent managing tools 48 | ### Maximize your investment in AI 49 | Our recent study with Accenture shows that AI-driven tools like GitHub Copilot, when integrated into daily workflows, can significantly boost productivity, job satisfaction, and overall code quality without adding complexity. Discover how to seamlessly integrate AI into your development processes with GitHub Copilot and see measurable impact across your organization. 50 | Learn moreContact sales 51 | You can’t perform that action at this time. 52 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_industry_nonprofits.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | GitHub for Nonprofits 5 | # Drive social impact one commit at a time 6 | GitHub for Nonprofits enables organizations to leverage technology to drive forward their missions and accelerate human progress. Verified nonprofits get exclusive access to a free GitHub Team plan or 25% off the GitHub Enterprise cloud plan. 7 | Join GitHub for Nonprofits 8 | ### Free access to a GitHub Team plan 9 | Receive access to advanced collaboration tools for individuals and organizations. 10 | ### 25% off GitHub Enterprise Cloud 11 | Get access to additional security, administrative, and customization options. 12 | ### Which plan is for you? 13 | GitHub Team offers collaboration for growing teams while GitHub Enterprise Cloud adds additional Actions and security features. 14 | ### Let GitHub power your mission 15 | Investing in GitHub is not just about adopting a tool—it's about empowering nonprofits to drive positive change and advance the Sustainable Development Goals. Join us at GitHub, where technology meets purpose, and together, let's create a more sustainable and equitable future for all. 16 | ![](https://images.ctfassets.net/8aevphvgewt8/5eLZS910X8I7t50ZXozO7Y/edc8badd29c9577799df5eb007027d66/Hifi_Handoff_2024-06-15.webp) 17 | ### Increase visibility and widen impact 18 | By hosting projects on GitHub, nonprofits can increase their visibility and reach a broader audience. Whether it's sharing code libraries, publishing research, or showcasing success stories, GitHub provides nonprofits with a platform to amplify their impact and attract support from donors, funders, volunteers, and partners. 19 | ![](https://images.ctfassets.net/8aevphvgewt8/3P0HtWCWbNDk98SNj4LKLL/587ef59ea9786685d6824a9ab741e30d/Hifi_Handoff_2024-06-152.webp) 20 | ### Tap into the open source community 21 | GitHub is home to the largest open source community on the planet - over 100 million developers. Whether you’re scaling your organization or just learning how to code, GitHub is your home. Join the world’s largest developer platform to build the innovations that empower humanity. 22 | ![](https://images.ctfassets.net/8aevphvgewt8/1hmSwxnWDgg9g4IgetWglf/410d1d3fa95ab8c0a06e1f6675f1d773/Hifi_Handoff_2024-06-153.webp) 23 | “ 24 | > GitHub provides us with a platform to amplify the critical needs of forcibly displaced persons and attract support from donors, volunteers, and partners, while also tapping into skills and resources of an incredible developer community. 25 | Seema IyerUSA for UNCHR 26 | ### Get started today 27 | Build your nonprofit on the world's most advanced developer platform. Verified nonprofits get exclusive access to a free GitHub Team plan or 25% off the GitHub Enterprise cloud plan. 28 | Join GitHub for NonprofitsContact us 29 | ### Frequently Asked Questions 30 | #### Who qualifies for GitHub for Nonprofits? 31 | Nonprofit organizations that are 501(c)(3) or equivalent and are non-governmental, non-academic, non-commercial, non-political in nature, and have no religious affiliation are eligible for a free GitHub Team Plan with unlimited private repositories and unlimited users or 25% off of GitHub Enterprise Cloud. 32 | #### What if our organization does not qualify for nonprofit status but works in the social sector? 33 | At this time, we only support registered 501(c)(3) or equivalent organizations. In the future, we hope to provide additional programmatic support to social sector organizations. 34 | #### What are the different GitHub pricing plans? 35 | GitHub offers free and paid plans for storing and collaborating on code. Some plans are available only to personal accounts, while other plans are available only to organization and enterprise accounts. For more information about accounts, see "Types of GitHub accounts." 36 | #### I have another question, how do I reach the team? 37 | If you would like to learn more about our programming, partner with us, or get in touch, contact our team today. 38 | You can’t perform that action at this time. 39 | -------------------------------------------------------------------------------- /docs/mcp_docs/tutorials_building-mcp-with-llms.md: -------------------------------------------------------------------------------- 1 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 2 | Search... 3 | ⌘K 4 | * Python SDK 5 | * TypeScript SDK 6 | * Java SDK 7 | * Kotlin SDK 8 | * Specification 9 | ##### Get Started 10 | * Introduction 11 | * Quickstart 12 | * Example Servers 13 | * Example Clients 14 | 15 | 16 | ##### Tutorials 17 | * Building MCP with LLMs 18 | * Debugging 19 | * Inspector 20 | 21 | 22 | ##### Concepts 23 | * Core architecture 24 | * Resources 25 | * Prompts 26 | * Tools 27 | * Sampling 28 | * Roots 29 | * Transports 30 | 31 | 32 | ##### Development 33 | * What's New 34 | * Roadmap 35 | * Contributing 36 | 37 | 38 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 39 | Search... 40 | ⌘K 41 | Search... 42 | Navigation 43 | Tutorials 44 | Building MCP with LLMs 45 | DocumentationSDKs 46 | DocumentationSDKs 47 | * GitHub 48 | This guide will help you use LLMs to help you build custom Model Context Protocol (MCP) servers and clients. We’ll be focusing on Claude for this tutorial, but you can do this with any frontier LLM. 49 | ## 50 | ​ 51 | Preparing the documentation 52 | Before starting, gather the necessary documentation to help Claude understand MCP: 53 | 1. Visit https://modelcontextprotocol.io/llms-full.txt and copy the full documentation text 54 | 2. Navigate to either the MCP TypeScript SDK or Python SDK repository 55 | 3. Copy the README files and other relevant documentation 56 | 4. Paste these documents into your conversation with Claude 57 | 58 | 59 | ## 60 | ​ 61 | Describing your server 62 | Once you’ve provided the documentation, clearly describe to Claude what kind of server you want to build. Be specific about: 63 | * What resources your server will expose 64 | * What tools it will provide 65 | * Any prompts it should offer 66 | * What external systems it needs to interact with 67 | 68 | 69 | For example: 70 | Copy 71 | ``` 72 | Build an MCP server that: 73 | - Connects to my company's PostgreSQL database 74 | - Exposes table schemas as resources 75 | - Provides tools for running read-only SQL queries 76 | - Includes prompts for common data analysis tasks 77 | 78 | ``` 79 | 80 | ## 81 | ​ 82 | Working with Claude 83 | When working with Claude on MCP servers: 84 | 1. Start with the core functionality first, then iterate to add more features 85 | 2. Ask Claude to explain any parts of the code you don’t understand 86 | 3. Request modifications or improvements as needed 87 | 4. Have Claude help you test the server and handle edge cases 88 | 89 | 90 | Claude can help implement all the key MCP features: 91 | * Resource management and exposure 92 | * Tool definitions and implementations 93 | * Prompt templates and handlers 94 | * Error handling and logging 95 | * Connection and transport setup 96 | 97 | 98 | ## 99 | ​ 100 | Best practices 101 | When building MCP servers with Claude: 102 | * Break down complex servers into smaller pieces 103 | * Test each component thoroughly before moving on 104 | * Keep security in mind - validate inputs and limit access appropriately 105 | * Document your code well for future maintenance 106 | * Follow MCP protocol specifications carefully 107 | 108 | 109 | ## 110 | ​ 111 | Next steps 112 | After Claude helps you build your server: 113 | 1. Review the generated code carefully 114 | 2. Test the server with the MCP Inspector tool 115 | 3. Connect it to Claude.app or other MCP clients 116 | 4. Iterate based on real usage and feedback 117 | 118 | 119 | Remember that Claude can help you modify and improve your server as requirements change over time. 120 | Need more guidance? Just ask Claude specific questions about implementing MCP features or troubleshooting issues that arise. 121 | Was this page helpful? 122 | YesNo 123 | Example ClientsDebugging 124 | On this page 125 | * Preparing the documentation 126 | * Describing your server 127 | * Working with Claude 128 | * Best practices 129 | * Next steps 130 | 131 | 132 | -------------------------------------------------------------------------------- /docs/uv-backup/features_security.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | ![](https://images.ctfassets.net/8aevphvgewt8/2YymXxRoWDQjhmQOOwzzqO/251bd0e39fcdc255abf2a1885aa58d7f/Hero_BG.webp?w=2400&fm=jpg&fl=progressive) 5 | GitHub Security 6 | # Security at every step 7 | AI-powered native application security testing 8 | Contact salesRequest a demo 9 | ### Enterprise-Grade 10 | Secure your public and private repositories and leverage the power of Copilot 11 | GitHub Advanced Security 12 | ### Powering DevSecOps 13 | Leverage automation and AI to help your developers ship secure code 14 | Get the checklist 15 | ### Security at Scale 16 | Learn how a global consulting firm automates security testing for 12K developers 17 | Read the customer story 18 | ### Find and fix vulnerabilities 7x faster 19 | With AI-powered application security testing tools embedded in your development workflow, GitHub Advanced Security outperforms non-native add-ons by delivering 7x faster remediation rates for identified vulnerabilities. 20 | Secure your code 21 | ![Build with 3 steps showing green circles with checkmarks](https://images.ctfassets.net/8aevphvgewt8/5yPX48aDjvoLk4kFmITU4l/9b668b6b1bbcbf3bfffeae7929933f43/Security_workflow.webp) 22 | ### vs code 23 | ![](https://images.ctfassets.net/8aevphvgewt8/7sE2CIxJtah2hxz17SuK2q/ffbabcdf221e48600cd9d6e97752e068/Security_codespaces.webp) 24 | _Find vulnerabilities and suppress false positives_ with more than 2,000 queries from GitHub and the open-source community. 25 | Learn more about CodeQL 26 | * Leverage machine learning to detect security issues in your pull requests and prevent new vulnerabilities from entering main. 27 | * Prioritize alerts and view exposure across the codebase to make sure you focus on what matters. Automatically resolve alerts with AI-powered auto-remediation. 28 | 29 | 30 | ### Software supply chains, secure by design 31 | GitHub supply chain security is designed for developers, built for speed, and free for everyone. All powered by a database of over 12,000 expert-reviewed advisories. 32 | Secure your software supply chain 33 | ![List of dependencies defined in pypi/requirements.txt](https://images.ctfassets.net/8aevphvgewt8/7hZcMpJI3S9NWgxOcISlSR/b15c3ac2ab1ac68c6d8ba68fdd6b9192/Security_dependencies.webp) 34 | ### Detect and prevent secret leaks 35 | Keep secrets out of your code with secret scanning and push protection, built on the foundation of 100+ partners and 200+ token types. Create custom patterns and detect leaked passwords, powered by AI. 36 | Secret scanning is now free for all public repositories 37 | ![Active secret detected and remediation steps](https://images.ctfassets.net/8aevphvgewt8/2duivPWNVDHSVaRJlCVLcW/d691b081ad0fc3ac19934567bb2b4b3b/Security_secret.webp) 38 | ### Complete visibility into your enterprise 39 | Security overview provides a cross-organizational view of security issues and trends so that you can focus on prioritizing remediation efforts and track progress over time. 40 | Explore GitHub Enterprise 41 | ![](https://images.ctfassets.net/8aevphvgewt8/5h3WqpvxE1NWcKK8FYjKVK/10395fe64dc2bb86738381ae6745640b/Security_visibility.webp) 42 | ### Be part of the world’s largest security community 43 | Report security issues, share security knowledge and grow with the community. Contribute to open source code scanning queries written by GitHub and leading security researchers. 44 | Publish a repository security advisory 45 | ![](https://images.ctfassets.net/8aevphvgewt8/39nUwrwKIu2DWMGKkXRyau/3340814471daa813b0fb9ddacf4135ba/Security_community.webp) 46 | ### Security at every step 47 | AI-powered native application security testing 48 | Contact salesRequest a demo 49 | ### Developer-first application security 50 | Take an in-depth look at the current state of application security. 51 | Learn more 52 | ### Proactive vs Reactive Security 53 | Prevent security issues from happening in the first place. 54 | Prevent security issues 55 | ### Static application security testing SAST 56 | Discover what SAST is and how to get started with SAST. 57 | Learn more about SAST 58 | You can’t perform that action at this time. 59 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_getting-started_features.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Features 3 | uv provides essential features for Python development — from installing Python and hacking on simple scripts to working on large projects that support multiple Python versions and platforms. 4 | uv's interface can be broken down into sections, which are usable independently or together. 5 | ## Python versions 6 | Installing and managing Python itself. 7 | * `uv python install`: Install Python versions. 8 | * `uv python list`: View available Python versions. 9 | * `uv python find`: Find an installed Python version. 10 | * `uv python pin`: Pin the current project to use a specific Python version. 11 | * `uv python uninstall`: Uninstall a Python version. 12 | 13 | 14 | See the guide on installing Python to get started. 15 | ## Scripts 16 | Executing standalone Python scripts, e.g., `example.py`. 17 | * `uv run`: Run a script. 18 | * `uv add --script`: Add a dependency to a script 19 | * `uv remove --script`: Remove a dependency from a script 20 | 21 | 22 | See the guide on running scripts to get started. 23 | ## Projects 24 | Creating and working on Python projects, i.e., with a `pyproject.toml`. 25 | * `uv init`: Create a new Python project. 26 | * `uv add`: Add a dependency to the project. 27 | * `uv remove`: Remove a dependency from the project. 28 | * `uv sync`: Sync the project's dependencies with the environment. 29 | * `uv lock`: Create a lockfile for the project's dependencies. 30 | * `uv run`: Run a command in the project environment. 31 | * `uv tree`: View the dependency tree for the project. 32 | * `uv build`: Build the project into distribution archives. 33 | * `uv publish`: Publish the project to a package index. 34 | 35 | 36 | See the guide on projects to get started. 37 | ## Tools 38 | Running and installing tools published to Python package indexes, e.g., `ruff` or `black`. 39 | * `uvx` / `uv tool run`: Run a tool in a temporary environment. 40 | * `uv tool install`: Install a tool user-wide. 41 | * `uv tool uninstall`: Uninstall a tool. 42 | * `uv tool list`: List installed tools. 43 | * `uv tool update-shell`: Update the shell to include tool executables. 44 | 45 | 46 | See the guide on tools to get started. 47 | ## The pip interface 48 | Manually managing environments and packages — intended to be used in legacy workflows or cases where the high-level commands do not provide enough control. 49 | Creating virtual environments (replacing `venv` and `virtualenv`): 50 | * `uv venv`: Create a new virtual environment. 51 | 52 | 53 | See the documentation on using environments for details. 54 | Managing packages in an environment (replacing `pip` and `pipdeptree`): 55 | * `uv pip install`: Install packages into the current environment. 56 | * `uv pip show`: Show details about an installed package. 57 | * `uv pip freeze`: List installed packages and their versions. 58 | * `uv pip check`: Check that the current environment has compatible packages. 59 | * `uv pip list`: List installed packages. 60 | * `uv pip uninstall`: Uninstall packages. 61 | * `uv pip tree`: View the dependency tree for the environment. 62 | 63 | 64 | See the documentation on managing packages for details. 65 | Locking packages in an environment (replacing `pip-tools`): 66 | * `uv pip compile`: Compile requirements into a lockfile. 67 | * `uv pip sync`: Sync an environment with a lockfile. 68 | 69 | 70 | See the documentation on locking environments for details. 71 | Important 72 | These commands do not exactly implement the interfaces and behavior of the tools they are based on. The further you stray from common workflows, the more likely you are to encounter differences. Consult the pip-compatibility guide for details. 73 | ## Utility 74 | Managing and inspecting uv's state, such as the cache, storage directories, or performing a self-update: 75 | * `uv cache clean`: Remove cache entries. 76 | * `uv cache prune`: Remove outdated cache entries. 77 | * `uv cache dir`: Show the uv cache directory path. 78 | * `uv tool dir`: Show the uv tool directory path. 79 | * `uv python dir`: Show the uv installed Python versions path. 80 | * `uv self update`: Update uv to the latest version. 81 | 82 | 83 | ## Next steps 84 | Read the guides for an introduction to each feature, check out concept pages for in-depth details about uv's features, or learn how to get help if you run into any problems. 85 | Back to top 86 | -------------------------------------------------------------------------------- /docs/uv-backup/uv_guides_package.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Building and publishing a package 3 | uv supports building Python packages into source and binary distributions via `uv build` and uploading them to a registry with `uv publish`. 4 | ## Preparing your project for packaging 5 | Before attempting to publish your project, you'll want to make sure it's ready to be packaged for distribution. 6 | If your project does not include a `[build-system]` definition in the `pyproject.toml`, uv will not build it by default. This means that your project may not be ready for distribution. Read more about the effect of declaring a build system in the project concept documentation. 7 | Note 8 | If you have internal packages that you do not want to be published, you can mark them as private: 9 | ``` 10 | [project] 11 | classifiers=["Private :: Do Not Upload"] 12 | 13 | ``` 14 | 15 | This setting makes PyPI reject your uploaded package from publishing. It does not affect security or privacy settings on alternative registries. 16 | We also recommend only generating per-project tokens: Without a PyPI token matching the project, it can't be accidentally published. 17 | ## Building your package 18 | Build your package with `uv build`: 19 | ``` 20 | $ uvbuild 21 | 22 | ``` 23 | 24 | By default, `uv build` will build the project in the current directory, and place the built artifacts in a `dist/` subdirectory. 25 | Alternatively, `uv build ` will build the package in the specified directory, while `uv build --package ` will build the specified package within the current workspace. 26 | Info 27 | By default, `uv build` respects `tool.uv.sources` when resolving build dependencies from the `build-system.requires` section of the `pyproject.toml`. When publishing a package, we recommend running `uv build --no-sources` to ensure that the package builds correctly when `tool.uv.sources` is disabled, as is the case when using other build tools, like `pypa/build`. 28 | ## Publishing your package 29 | Publish your package with `uv publish`: 30 | ``` 31 | $ uvpublish 32 | 33 | ``` 34 | 35 | Set a PyPI token with `--token` or `UV_PUBLISH_TOKEN`, or set a username with `--username` or `UV_PUBLISH_USERNAME` and password with `--password` or `UV_PUBLISH_PASSWORD`. For publishing to PyPI from GitHub Actions, you don't need to set any credentials. Instead, add a trusted publisher to the PyPI project. 36 | Note 37 | PyPI does not support publishing with username and password anymore, instead you need to generate a token. Using a token is equivalent to setting `--username __token__` and using the token as password. 38 | If you're using a custom index through `[[tool.uv.index]]`, add `publish-url` and use `uv publish --index `. For example: 39 | ``` 40 | [[tool.uv.index]] 41 | name="testpypi" 42 | url="https://test.pypi.org/simple/" 43 | publish-url="https://test.pypi.org/legacy/" 44 | explicit=true 45 | 46 | ``` 47 | 48 | Note 49 | When using `uv publish --index `, the `pyproject.toml` must be present, i.e., you need to have a checkout step in a publish CI job. 50 | Even though `uv publish` retries failed uploads, it can happen that publishing fails in the middle, with some files uploaded and some files still missing. With PyPI, you can retry the exact same command, existing identical files will be ignored. With other registries, use `--check-url ` with the index URL (not the publish URL) the packages belong to. When using `--index`, the index URL is used as check URL. uv will skip uploading files that are identical to files in the registry, and it will also handle raced parallel uploads. Note that existing files need to match exactly with those previously uploaded to the registry, this avoids accidentally publishing source distribution and wheels with different contents for the same version. 51 | ## Installing your package 52 | Test that the package can be installed and imported with `uv run`: 53 | ``` 54 | $ uvrun--with--no-project--python-c"import " 55 | 56 | ``` 57 | 58 | The `--no-project` flag is used to avoid installing the package from your local project directory. 59 | Tip 60 | If you have recently installed the package, you may need to include the `--refresh-package ` option to avoid using a cached version of the package. 61 | ## Next steps 62 | To learn more about publishing packages, check out the PyPA guides on building and publishing. 63 | Or, read on for guides on integrating uv with other software. 64 | Back to top 65 | -------------------------------------------------------------------------------- /memory-bank/progress.md: -------------------------------------------------------------------------------- 1 | # Progress 2 | 3 | ## Project Status: Planning Phase 4 | 5 | ### What Works 6 | - Project vision and goals are established 7 | - Memory Bank is set up with initial documentation 8 | - High-level system architecture is defined 9 | - Technology decisions made (Python, SQLite, reuse of existing crawler) 10 | - Project phases with clear definitions of done are established 11 | - Existing crawler code has been identified and analyzed 12 | - Project structure has been set up 13 | - Core components have been implemented: 14 | - Crawler adapter that reuses existing code 15 | - File-based documentation storage 16 | - Basic search functionality 17 | - MCP tool definitions and server implementation 18 | - HTTP server for direct API access 19 | - FastMCP implementation for standard MCP integration 20 | - CLI interface with multiple server options 21 | - Tests for all components are working 22 | - Integration with Claude for Desktop is supported 23 | 24 | ### What's In Progress 25 | - Testing with real-world documentation 26 | - Documentation refinement 27 | 28 | ### What's Left To Build 29 | - End-to-end testing with actual documentation sources 30 | - User documentation and usage examples 31 | - Refinements based on user feedback 32 | - Advanced phases still to be implemented: 33 | - Phase 2: Expanding MCP Tool capabilities 34 | - Phase 3: Intelligent Documentation Retrieval with vector database 35 | - Phase 4: Remote Documentation Server 36 | 37 | ## Milestone Progress 38 | 39 | ### Phase 1: Documentation Crawler Integration 40 | - ✅ Defined scope and requirements 41 | - ✅ Selected technologies (Python, SQLite) 42 | - ✅ Established definition of done 43 | - ✅ Identified existing crawler code to reuse 44 | - ✅ Set up project structure 45 | - ✅ Implement filesystem-based storage (simpler than original SQLite plan) 46 | - ✅ Implement crawler adapter 47 | - ✅ Create CLI interface 48 | - ✅ Develop testing suite 49 | - 🔲 Complete documentation 50 | 51 | ### Phase 2: Basic MCP Tool Implementation 52 | - ✅ Defined scope and requirements 53 | - ✅ Established definition of done 54 | - ✅ Define MCP tool interfaces 55 | - ✅ Implement basic search and retrieval logic 56 | - ✅ Create testing suite for tools 57 | - ✅ Develop simple server for LLM tool calls 58 | - ✅ Create example scripts for testing 59 | - 🔲 Complete documentation 60 | 61 | ### Phase 3: Intelligent Documentation Retrieval 62 | - ✅ Defined scope and requirements 63 | - ✅ Established definition of done 64 | - 🔲 Research RAG and vector database options 65 | - 🔲 Implement vector database migration 66 | - 🔲 Develop improved relevance algorithms 67 | - 🔲 Enhance context understanding 68 | - 🔲 Create benchmarking suite 69 | - 🔲 Complete documentation 70 | 71 | ### Phase 4: Remote Documentation Server 72 | - ✅ Defined scope and requirements 73 | - ✅ Established definition of done 74 | - 🔲 Design client-server protocol 75 | - 🔲 Implement remote server 76 | - 🔲 Develop authentication system 77 | - 🔲 Create synchronization mechanisms 78 | - 🔲 Implement security features 79 | - 🔲 Complete documentation 80 | 81 | ## Known Issues 82 | - Crawler may encounter rate limiting with some documentation sites 83 | - Section extraction from markdown could be improved for complex documents 84 | - Error handling is minimal in some components 85 | 86 | ## Technical Debt 87 | - Need to add proper error handling for edge cases 88 | - Should implement logging throughout the codebase 89 | - Test coverage could be improved with more end-to-end tests 90 | - Should add type annotations more consistently 91 | 92 | ## Next Immediate Tasks 93 | 1. Implement a simple MCP server for LLM tool calls 94 | 2. Create comprehensive documentation for the project 95 | 3. Perform end-to-end testing with actual documentation sources 96 | 4. Gather user feedback and make refinements 97 | 98 | ## Key Achievements 99 | - Established clear project vision with well-defined phases 100 | - Created comprehensive Memory Bank to guide development 101 | - Defined standalone value for each project phase 102 | - Established clear criteria for testing and definition of done 103 | - Successfully integrated existing crawler code to accelerate development 104 | - Implemented a complete working MVP of the documentation assistant 105 | - Created a clean, modular architecture with well-defined components 106 | - All tests are passing for the core functionality -------------------------------------------------------------------------------- /docs/uv-backup/sponsors.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | GitHub Sponsors 5 | # Support the developers who power open source 6 | See your top dependenciesGet sponsored 7 | ![Become a sponsor to Mono Octocat showing $12,000 a month with a button with text "Sponsor"](https://images.ctfassets.net/8aevphvgewt8/240toQ0ZKtCDivfrF8vdcj/af5f59a4164a83a205a9c589ecc882b0/Hero.webp?fm=webp) 8 | ### $40M+ 9 | Given back to our maintainers 10 | ### 103 11 | Regions supported globally 12 | ### 4.2K+ 13 | Organizations sponsoring 14 | ### For maintainers 15 | Launch a page in minutes and showcase Sponsors buttons on your GitHub profile and repositories! You will automatically appear in worldwide recommendations to partners who are eager to invest in their open source dependencies. 16 | Get sponsored 17 | ![List of maintainers each with a "Sponsor" button](https://images.ctfassets.net/8aevphvgewt8/42Fzdk9a23AuuYuTViBVVJ/c64b9444b08668d2992e78463a853d82/Image.webp) 18 | ### For sponsors 19 | Find and fund your dependencies in a single transaction. The discovery and bulk sponsorship tools are easy to use. Flexible payment enables you to choose when and how you pay. Corporations like Microsoft like it because all their payments go out as a single invoice. 20 | Learn about invoiced billing 21 | ![Chart displaying months a total amount spent](https://images.ctfassets.net/8aevphvgewt8/3z9uFxoAGAOnmfu9KsZACQ/00b55684a5331b2d917e4939d966a589/Image_Area__60_40_.webp) 22 | ### Help open source thrive 23 | Everyone should be able to contribute to open source. Making open source a viable, financially rewarding career path helps contribute to our digital infrastructure. More funding, more projects, more software to power our world. 24 | See your top dependencies 25 | ![Popup displaying "$15,000 a month" with a progress bar showing 87% towards $15,000 goal](https://images.ctfassets.net/8aevphvgewt8/6wiE9miII032Gezk0o9Te1/ee11fc2f683d83dbbf09b2d69bd75f96/Image_Area__60_40__2.webp) 26 | “ 27 | > Shopify uses GitHub Sponsors to efficiently manage and fund projects within the open source community, tailored to the needs of recipients. 28 | ![Shopify logo](https://images.ctfassets.net/8aevphvgewt8/HLOaLspfdGpLJFaivD2W1/cc542f8a6efbe9d935acae8700d37197/shopify_glyph.png?fm=webp&w=120&q=90) 29 | Azmat YuhannaSenior Engineering Operations Manager, Shopify 30 | ### Invest in open source. It powers your world. 31 | See your top dependenciesGet sponsored 32 | ### The internet depends on open source, everywhere 33 | ### Comprehensive website security and health monitoring with performance analysis 34 | web-check 35 | Web-Check provides real-time monitoring for uptime, speed, and user experience, trusted by businesses like Amazon, Shopify, and Airbnb. 36 | Sponsor web-check 37 | ### Intuitive, open-source interface for native GenAI applications 38 | OpenWebUI 39 | OpenWebUI simplifies the development of interactive GenAI apps using LLMs, used by developers at companies like Microsoft, IBM, and GitHub. 40 | Sponsor OpenWebUI 41 | ### A command line tool and library for transferring data with URL syntax 42 | cURL 43 | cURL is included in almost every modern device–smartphones, cars, TVs, laptops, servers, consoles, printers, and beyond. 44 | Sponsor cURL 45 | ### Frequently asked questions 46 | #### How do I sponsor a project? 47 | Sign in and start by navigating to your dependencies, your explore tab, trending repositories, or collections. When a repository has the Sponsor graphic, you can sponsor them directly. 48 | #### How do I get paid for my contributions? 49 | You can become a sponsored developer by joining GitHub Sponsors, completing your sponsored developer profile, creating sponsorship tiers, submitting your bank and tax information, and enabling two-factor authentication for your account on GitHub.com. Learn more about getting paid for contributions 50 | #### Do I need to fill out a tax form to receive sponsorships? 51 | Yes. Your tax information must be on file in order for GitHub to make payments to your bank account. The required tax documents may vary based on your location. 52 | Note that we do our best to help you with the Sponsors program, but we’re unable to provide tax guidance. 53 | Learn more about tax information for GitHub Sponsors 54 | You can’t perform that action at this time. 55 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # TheAlmanac 2 | 3 | A documentation assistant leveraging Model Context Protocol (MCP) to help programmers access the most up-to-date and relevant information from API and software documentation. 4 | 5 | ## Features 6 | 7 | - **Documentation Crawler**: Automatically download and store documentation locally 8 | - **Simple Search**: Find relevant documentation sections quickly 9 | - **MCP Integration**: Provide LLMs with tools to access documentation 10 | - **File-based Storage**: Efficiently organize documentation in a simple file structure 11 | - **MCP Server**: HTTP server for LLM tool access 12 | 13 | ## Installation 14 | 15 | ```bash 16 | # Clone the repository 17 | git clone https://github.com/yourusername/TheAlmanac.git 18 | cd TheAlmanac 19 | 20 | # Install dependencies with UV 21 | uv pip install -e . 22 | ``` 23 | 24 | ## Usage 25 | 26 | ### Managing Documentation Sources 27 | 28 | ```bash 29 | # Add a documentation source 30 | almanac add python https://docs.python.org/3/ 31 | 32 | # List all documentation sources 33 | almanac list 34 | 35 | # Download documentation 36 | almanac download python 37 | 38 | # Remove a documentation source 39 | almanac remove python 40 | ``` 41 | 42 | ### Searching Documentation 43 | 44 | ```bash 45 | # Search all documentation 46 | almanac search "context manager" 47 | 48 | # Search a specific source 49 | almanac search "context manager" --source python 50 | 51 | # Search with more context 52 | almanac search "context manager" --context-lines 5 53 | ``` 54 | 55 | ### Running the MCP Server 56 | 57 | ```bash 58 | # Start the HTTP server (for direct API access) 59 | almanac serve --transport http 60 | 61 | # Start the MCP server (for integration with MCP clients like Claude for Desktop) 62 | almanac serve --transport stdio 63 | 64 | # Start on a specific host and port (for HTTP transport) 65 | almanac serve --transport http --host 0.0.0.0 --port 9000 66 | ``` 67 | 68 | ## MCP Tools 69 | 70 | TheAlmanac provides the following MCP tools: 71 | 72 | 1. **search_documentation**: Search for relevant documentation 73 | 2. **get_documentation**: Get a specific document or section 74 | 3. **download_documentation**: Download a new documentation source 75 | 4. **list_documentation**: List available documentation sources 76 | 77 | ## Example Scripts 78 | 79 | The `scripts` directory contains example scripts for testing and demonstrating TheAlmanac: 80 | 81 | - `test_mcp_tools.py`: Directly test MCP tools 82 | - `test_mcp_server.py`: Test the MCP server with HTTP requests 83 | - `test_mcp_fastmcp.py`: Test the FastMCP implementation directly 84 | - `example_workflow.py`: Run a complete workflow example 85 | 86 | ### Example MCP Tool Usage 87 | 88 | ```bash 89 | # Test the search tool (HTTP server) 90 | ./scripts/test_mcp_tools.py search "installation" 91 | 92 | # Test getting a specific document (HTTP server) 93 | ./scripts/test_mcp_tools.py get python index.md 94 | 95 | # Test the search tool (FastMCP) 96 | ./scripts/test_mcp_fastmcp.py search "installation" 97 | 98 | # Test listing documentation (FastMCP) 99 | ./scripts/test_mcp_fastmcp.py list 100 | 101 | # Test the complete workflow 102 | ./scripts/example_workflow.py 103 | ``` 104 | 105 | ### MCP Integration with Claude for Desktop 106 | 107 | To integrate TheAlmanac with Claude for Desktop: 108 | 109 | 1. Make sure Claude for Desktop is installed 110 | 2. Edit the Claude for Desktop configuration file: 111 | ```bash 112 | # For macOS: 113 | code ~/Library/Application\ Support/Claude/claude_desktop_config.json 114 | ``` 115 | 116 | 3. Add TheAlmanac as an MCP server: 117 | ```json 118 | { 119 | "mcpServers": { 120 | "the-almanac": { 121 | "command": "/path/to/python", 122 | "args": [ 123 | "-m", 124 | "almanac.cli.commands", 125 | "serve", 126 | "--transport", 127 | "stdio" 128 | ] 129 | } 130 | } 131 | } 132 | ``` 133 | 134 | 4. Restart Claude for Desktop 135 | 5. Look for the hammer icon to access TheAlmanac tools 136 | 137 | ## Development 138 | 139 | ```bash 140 | # Install development dependencies 141 | uv pip install -e ".[dev]" 142 | 143 | # Run tests 144 | uv run pytest 145 | ``` 146 | 147 | ## Adding Dependencies 148 | 149 | ```bash 150 | # Add a production dependency 151 | uv add package_name 152 | 153 | # Add a development dependency 154 | uv add --dev package_name 155 | ``` 156 | 157 | ## License 158 | 159 | MIT -------------------------------------------------------------------------------- /docs/uv-backup/uv_configuration_authentication.md: -------------------------------------------------------------------------------- 1 | Skip to content 2 | # Authentication 3 | ## Git authentication 4 | uv allows packages to be installed from Git and supports the following schemes for authenticating with private repositories. 5 | Using SSH: 6 | * `git+ssh://git@/...` (e.g., `git+ssh://git@github.com/astral-sh/uv`) 7 | * `git+ssh://git@/...` (e.g., `git+ssh://git@github.com-key-2/astral-sh/uv`) 8 | 9 | 10 | See the GitHub SSH documentation for more details on how to configure SSH. 11 | Using a password or token: 12 | * `git+https://:@/...` (e.g., `git+https://git:github_pat_asdf@github.com/astral-sh/uv`) 13 | * `git+https://@/...` (e.g., `git+https://github_pat_asdf@github.com/astral-sh/uv`) 14 | * `git+https://@/...` (e.g., `git+https://git@github.com/astral-sh/uv`) 15 | 16 | 17 | When using a GitHub personal access token, the username is arbitrary. GitHub does not support logging in with password directly, although other hosts may. If a username is provided without credentials, you will be prompted to enter them. 18 | If there are no credentials present in the URL and authentication is needed, the Git credential helper will be queried. 19 | ## HTTP authentication 20 | uv supports credentials over HTTP when querying package registries. 21 | Authentication can come from the following sources, in order of precedence: 22 | * The URL, e.g., `https://:@/...` 23 | * A `.netrc` configuration file 24 | * A keyring provider (requires opt-in) 25 | 26 | 27 | If authentication is found for a single net location (scheme, host, and port), it will be cached for the duration of the command and used for other queries to that net location. Authentication is not cached across invocations of uv. 28 | `.netrc` authentication is enabled by default, and will respect the `NETRC` environment variable if defined, falling back to `~/.netrc` if not. 29 | To enable keyring-based authentication, pass the `--keyring-provider subprocess` command-line argument to uv, or set `UV_KEYRING_PROVIDER=subprocess`. 30 | Authentication may be used for hosts specified in the following contexts: 31 | * `[index]` 32 | * `index-url` 33 | * `extra-index-url` 34 | * `find-links` 35 | * `package @ https://...` 36 | 37 | 38 | See the index authentication documentation for details on authenticating index URLs. 39 | See the `pip` compatibility guide for details on differences from `pip`. 40 | ## Authentication with alternative package indexes 41 | See the alternative indexes integration guide for details on authentication with popular alternative Python package indexes. 42 | ## Custom CA certificates 43 | By default, uv loads certificates from the bundled `webpki-roots` crate. The `webpki-roots` are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS, where reading the system trust store incurs a significant delay). 44 | However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store. To instruct uv to use the system's trust store, run uv with the `--native-tls` command-line flag, or set the `UV_NATIVE_TLS` environment variable to `true`. 45 | If a direct path to the certificate is required (e.g., in CI), set the `SSL_CERT_FILE` environment variable to the path of the certificate bundle, to instruct uv to use that file instead of the system's trust store. 46 | If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment variable to the path of the PEM formatted file containing the certificate followed by the private key. 47 | Finally, if you're using a setup in which you want to trust a self-signed certificate or otherwise disable certificate verification, you can instruct uv to allow insecure connections to dedicated hosts via the `allow-insecure-host` configuration option. For example, adding the following to `pyproject.toml` will allow insecure connections to `example.com`: 48 | ``` 49 | [tool.uv] 50 | allow-insecure-host=["example.com"] 51 | 52 | ``` 53 | 54 | `allow-insecure-host` expects to receive a hostname (e.g., `localhost`) or hostname-port pair (e.g., `localhost:8080`), and is only applicable to HTTPS connections, as HTTP connections are inherently insecure. 55 | Use `allow-insecure-host` with caution and only in trusted environments, as it can expose you to security risks due to the lack of certificate verification. 56 | Back to top 57 | -------------------------------------------------------------------------------- /almanac/tasks/store.py: -------------------------------------------------------------------------------- 1 | """Task result storage implementation.""" 2 | import logging 3 | import sqlite3 4 | from datetime import datetime, timedelta 5 | from pathlib import Path 6 | from typing import Optional 7 | from uuid import UUID 8 | 9 | from almanac.tasks.models import TaskResult 10 | 11 | logger = logging.getLogger(__name__) 12 | 13 | 14 | class TaskStore: 15 | """SQLite-backed task result store.""" 16 | 17 | def __init__(self, db_path: Optional[Path] = None): 18 | """Initialize the task store. 19 | 20 | Args: 21 | db_path: Path to SQLite database file. If None, uses 'tasks.db' 22 | in the current directory. 23 | """ 24 | self.db_path = db_path or Path("tasks.db") 25 | self._init_db() 26 | 27 | def _init_db(self): 28 | """Initialize the database schema.""" 29 | with sqlite3.connect(self.db_path) as conn: 30 | conn.execute(""" 31 | CREATE TABLE IF NOT EXISTS task_results ( 32 | id TEXT PRIMARY KEY, 33 | task_id TEXT NOT NULL, 34 | content TEXT NOT NULL, 35 | error TEXT, 36 | created_at TEXT NOT NULL, 37 | FOREIGN KEY (task_id) REFERENCES tasks(id) 38 | ) 39 | """) 40 | conn.commit() 41 | 42 | async def store_result( 43 | self, task_id: UUID, content: str, error: Optional[str] = None 44 | ) -> UUID: 45 | """Store a task result. 46 | 47 | Args: 48 | task_id: ID of the task this result is for 49 | content: Result content 50 | error: Optional error message if task failed 51 | 52 | Returns: 53 | UUID of the stored result 54 | """ 55 | result = TaskResult.create(task_id, content, error) 56 | 57 | with sqlite3.connect(self.db_path) as conn: 58 | conn.execute( 59 | """ 60 | INSERT INTO task_results ( 61 | id, task_id, content, error, created_at 62 | ) VALUES (?, ?, ?, ?, ?) 63 | """, 64 | ( 65 | str(result.id), 66 | str(result.task_id), 67 | result.content, 68 | result.error, 69 | result.created_at.isoformat() 70 | ) 71 | ) 72 | conn.commit() 73 | 74 | logger.info(f"Stored result {result.id} for task {task_id}") 75 | return result.id 76 | 77 | async def get_result(self, task_id: UUID) -> Optional[TaskResult]: 78 | """Get the result for a task. 79 | 80 | Args: 81 | task_id: ID of the task to get result for 82 | 83 | Returns: 84 | The task result if found, None otherwise 85 | """ 86 | with sqlite3.connect(self.db_path) as conn: 87 | cursor = conn.execute( 88 | """ 89 | SELECT id, task_id, content, error, created_at 90 | FROM task_results 91 | WHERE task_id = ? 92 | """, 93 | (str(task_id),) 94 | ) 95 | row = cursor.fetchone() 96 | 97 | if not row: 98 | return None 99 | 100 | return TaskResult( 101 | id=UUID(row[0]), 102 | task_id=UUID(row[1]), 103 | content=row[2], 104 | error=row[3], 105 | created_at=datetime.fromisoformat(row[4]) 106 | ) 107 | 108 | async def cleanup_old_results(self, days: int = 7): 109 | """Remove results older than the specified number of days. 110 | 111 | Args: 112 | days: Number of days to keep results for 113 | """ 114 | cutoff = ( 115 | datetime.utcnow() - timedelta(days=days) 116 | ).isoformat() 117 | 118 | with sqlite3.connect(self.db_path) as conn: 119 | cursor = conn.execute( 120 | """ 121 | DELETE FROM task_results 122 | WHERE created_at < ? 123 | """, 124 | (cutoff,) 125 | ) 126 | conn.commit() 127 | 128 | logger.info( 129 | f"Cleaned up {cursor.rowcount} results older than {days} days" 130 | ) 131 | -------------------------------------------------------------------------------- /docs/mcp_docs/development_roadmap.md: -------------------------------------------------------------------------------- 1 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 2 | Search... 3 | ⌘K 4 | * Python SDK 5 | * TypeScript SDK 6 | * Java SDK 7 | * Kotlin SDK 8 | * Specification 9 | ##### Get Started 10 | * Introduction 11 | * Quickstart 12 | * Example Servers 13 | * Example Clients 14 | 15 | 16 | ##### Tutorials 17 | * Building MCP with LLMs 18 | * Debugging 19 | * Inspector 20 | 21 | 22 | ##### Concepts 23 | * Core architecture 24 | * Resources 25 | * Prompts 26 | * Tools 27 | * Sampling 28 | * Roots 29 | * Transports 30 | 31 | 32 | ##### Development 33 | * What's New 34 | * Roadmap 35 | * Contributing 36 | 37 | 38 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 39 | Search... 40 | ⌘K 41 | Search... 42 | Navigation 43 | Development 44 | Roadmap 45 | DocumentationSDKs 46 | DocumentationSDKs 47 | * GitHub 48 | The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and future direction for **the first half of 2025** , though these may change significantly as the project develops. 49 | The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. This is also not an _exhaustive_ list; we may incorporate work that isn’t mentioned here. 50 | We encourage community participation! Each section links to relevant discussions where you can learn more and contribute your thoughts. 51 | ## 52 | ​ 53 | Remote MCP Support 54 | Our top priority is improving remote MCP connections, allowing clients to securely connect to MCP servers over the internet. Key initiatives include: 55 | * **Authentication & Authorization**: Adding standardized auth capabilities, particularly focused on OAuth 2.0 support. 56 | * **Service Discovery**: Defining how clients can discover and connect to remote MCP servers. 57 | * **Stateless Operations**: Thinking about whether MCP could encompass serverless environments too, where they will need to be mostly stateless. 58 | 59 | 60 | ## 61 | ​ 62 | Reference Implementations 63 | To help developers build with MCP, we want to offer documentation for: 64 | * **Client Examples** : Comprehensive reference client implementation(s), demonstrating all protocol features 65 | * **Protocol Drafting** : Streamlined process for proposing and incorporating new protocol features 66 | 67 | 68 | ## 69 | ​ 70 | Distribution & Discovery 71 | Looking ahead, we’re exploring ways to make MCP servers more accessible. Some areas we may investigate include: 72 | * **Package Management** : Standardized packaging format for MCP servers 73 | * **Installation Tools** : Simplified server installation across MCP clients 74 | * **Sandboxing** : Improved security through server isolation 75 | * **Server Registry** : A common directory for discovering available MCP servers 76 | 77 | 78 | ## 79 | ​ 80 | Agent Support 81 | We’re expanding MCP’s capabilities for complex agentic workflows, particularly focusing on: 82 | * **Hierarchical Agent Systems**: Improved support for trees of agents through namespacing and topology awareness. 83 | * **Interactive Workflows**: Better handling of user permissions and information requests across agent hierarchies, and ways to send output to users instead of models. 84 | * **Streaming Results**: Real-time updates from long-running agent operations. 85 | 86 | 87 | ## 88 | ​ 89 | Broader Ecosystem 90 | We’re also invested in: 91 | * **Community-Led Standards Development** : Fostering a collaborative ecosystem where all AI providers can help shape MCP as an open standard through equal participation and shared governance, ensuring it meets the needs of diverse AI applications and use cases. 92 | * **Additional Modalities**: Expanding beyond text to support audio, video, and other formats. 93 | * [**Standardization**] Considering standardization through a standardization body. 94 | 95 | 96 | ## 97 | ​ 98 | Get Involved 99 | We welcome community participation in shaping MCP’s future. Visit our GitHub Discussions to join the conversation and contribute your ideas. 100 | Was this page helpful? 101 | YesNo 102 | What's NewContributing 103 | On this page 104 | * Remote MCP Support 105 | * Reference Implementations 106 | * Distribution & Discovery 107 | * Agent Support 108 | * Broader Ecosystem 109 | * Get Involved 110 | 111 | 112 | -------------------------------------------------------------------------------- /docs/uv-backup/solutions_industry_healthcare.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | Healthcare solutions 5 | # Empower healthcare development with a secure, AI-powered platform 6 | By incorporating AI into developer workflows, you can build secure patient care solutions at scale. 7 | Start a free trialContact sales 8 | ### Enhance patient care 9 | Facilitate rapid innovation so you can implement the latest technologies more reliably. 10 | ### Unlock engineering potential 11 | Empower developer collaboration, productivity, and creativity at scale. 12 | ### Streamline healthcare development 13 | Focus on delivering impactful patient outcomes by priming your engineering staff for growth. 14 | ## Lorem Ipsum 15 | Doctolib 16 | 3M 17 | Philips 18 | Amplifon 19 | Procter and Gamble 20 | ### Drive healthcare innovation with AI 21 | By enabling your developers to code up to 55% faster, you can stay ahead of advancements and innovate services while remaining secure and compliant. 22 | Explore GitHub Copilot 23 | ![](https://images.ctfassets.net/8aevphvgewt8/10miox7JNqtL3gGpCf1sRS/d0923ff169cd8d2015174a51d503c09e/AI-2.webp) 24 | ### Protect patient data 25 | Create more secure healthcare applications by detecting vulnerabilities in your codebase and preventing credentials from being exposed. 26 | Explore GitHub Advanced Security 27 | ![](https://images.ctfassets.net/8aevphvgewt8/4pufdRqmUtEHxCRy4SbGq6/566eeeb0beee0f3b8c92fb3831d2290d/Security-2.webp) 28 | ### Automate manual tasks 29 | Make life easier for developers. Reduce time-to-market and improve responsiveness to patients and stakeholders by using enterprise-ready, scalable CI/CD. 30 | Explore GitHub Actions 31 | ![Test passing connecting to 3 steps that are in progress](https://images.ctfassets.net/8aevphvgewt8/7JldMWj69GEj43gx9cIf5K/4d53dbc663417142a5dd826c79d4215f/Automation-2.webp) 32 | ### +88%more productivity with GitHub Enterprise 33 | ### 1minset-up time for largest repo with GitHub Codespaces 34 | ### ~25%increase in developer speed with GitHub Copilot 35 | ### Read how Doctolib fostered a culture of reusability and simplified the CI/CD process with GitHub. 36 | Read the customer story 37 | ![](https://images.ctfassets.net/8aevphvgewt8/4YhMUqnLuWiQgj6qwTm2ho/52435451d366756abd1962d963f630ed/doctor-and-child-patient.png) 38 | ### 3M transforms its software toolchain to bring cutting-edge science to customers, faster. 39 | ![Tower with 3M at the top](https://images.ctfassets.net/8aevphvgewt8/4VrAcl170GPqwcaaflY1zt/0ca1a1e24a949889bc5c85482406a6f3/3M_tower.webp?fm=webp) 40 | Read story 41 | ### Philips builds and deploys digital health technology faster with innersource on GitHub. 42 | ![doctor](https://images.ctfassets.net/8aevphvgewt8/365n7ERNkjzhn9SPqfNuqJ/b3829500dfb573e878c1ede4d389e1f5/doctor-small.webp?fm=webp) 43 | Read story 44 | ### GitHub brings DevOps to life and enables streamlined developer experiences at Procter & Gamble. 45 | ![Building with 2 towers and flags](https://images.ctfassets.net/8aevphvgewt8/4iJEc5NkUQTrz8ivwmAw8B/de3104ffb1190f47c4b60074f10f71ba/pg2-1.webp?fm=webp) 46 | Read story 47 | “ 48 | > Healthcare organizations want a service that provides a world-class experience for patients and improves people’s lives. GitHub helps us meet and exceed those expectations. 49 | ![Philips](https://images.ctfassets.net/8aevphvgewt8/6xGgTMaGLg4g8UicslH09h/5b895cf3b6b33f2a253a9e54b5136df7/Philips_Wordmark-ALI-global.jpeg?fm=webp&w=120&q=90) 50 | David TerolProgram director at the Philips Software Center of Excellence 51 | ### DevOps strategies for healthcare innovation, amplified by GitHub 52 | Trusted by 90% of the Fortune 100, GitHub helps millions of developers and companies collaborate, build, and deliver secure software faster. And with thousands of DevOps integrations, developers can build smarter from day one with the tools they know and love—or discover new ones. 53 | Start a free trialContact sales 54 | ### Additional resources 55 | ### Find the right DevOps platform 56 | Narrow your search with the 2024 Gartner® Magic Quadrant™ for DevOps Platforms report. 57 | Get the Gartner report 58 | ### What is DevOps? 59 | By bringing people, processes, and products together, DevOps enables development teams to continuously deliver value. 60 | Learn more about DevOps 61 | ### Discover innersource 62 | This practice empowers developers to save time and energy by bringing methodologies from open source into their internal development. 63 | Read more on Innersouce 64 | You can’t perform that action at this time. 65 | -------------------------------------------------------------------------------- /scripts/test_mcp_tools.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """Test script for MCP tools.""" 3 | import argparse 4 | import asyncio 5 | import json 6 | import logging 7 | import sys 8 | from pathlib import Path 9 | 10 | # Add parent directory to path 11 | sys.path.insert(0, str(Path(__file__).parent.parent)) 12 | 13 | from almanac.mcp.tools import ( 14 | SearchDocumentationTool, 15 | GetDocumentationTool, 16 | DownloadDocumentationTool, 17 | ListDocumentationTool 18 | ) 19 | 20 | # Configure logging 21 | logging.basicConfig( 22 | level=logging.INFO, 23 | format="%(asctime)s - %(levelname)s - %(message)s" 24 | ) 25 | logger = logging.getLogger(__name__) 26 | 27 | 28 | async def test_search_documentation(docs_dir: str, query: str, source_name: str = None): 29 | """Test search documentation tool.""" 30 | logger.info(f"Testing search documentation with query: {query}") 31 | 32 | tool = SearchDocumentationTool(docs_dir=docs_dir) 33 | params = {"query": query} 34 | 35 | if source_name: 36 | params["source_name"] = source_name 37 | 38 | result = await tool.execute(params) 39 | print(json.dumps(result, indent=2)) 40 | 41 | 42 | async def test_get_documentation( 43 | docs_dir: str, source_name: str, document_name: str, heading: str = None 44 | ): 45 | """Test get documentation tool.""" 46 | logger.info(f"Testing get documentation for {source_name}/{document_name}") 47 | 48 | tool = GetDocumentationTool(docs_dir=docs_dir) 49 | params = {"source_name": source_name, "document_name": document_name} 50 | 51 | if heading: 52 | params["heading"] = heading 53 | 54 | result = await tool.execute(params) 55 | print(json.dumps(result, indent=2)) 56 | 57 | 58 | async def test_download_documentation(docs_dir: str, source_name: str, url: str = None): 59 | """Test download documentation tool.""" 60 | logger.info(f"Testing download documentation for {source_name}") 61 | 62 | tool = DownloadDocumentationTool(docs_dir=docs_dir) 63 | params = {"source_name": source_name} 64 | 65 | if url: 66 | params["url"] = url 67 | 68 | result = await tool.execute(params) 69 | print(json.dumps(result, indent=2)) 70 | 71 | 72 | async def test_list_documentation(docs_dir: str, source_name: str = None): 73 | """Test list documentation tool.""" 74 | logger.info("Testing list documentation") 75 | 76 | tool = ListDocumentationTool(docs_dir=docs_dir) 77 | params = {} 78 | 79 | if source_name: 80 | params["source_name"] = source_name 81 | 82 | result = await tool.execute(params) 83 | print(json.dumps(result, indent=2)) 84 | 85 | 86 | def main(): 87 | """Main function.""" 88 | parser = argparse.ArgumentParser(description="Test MCP tools") 89 | parser.add_argument("--docs-dir", default="docs", help="Documentation directory") 90 | 91 | subparsers = parser.add_subparsers(dest="command", help="Tool to test") 92 | 93 | # Search documentation 94 | search_parser = subparsers.add_parser("search", help="Test search documentation tool") 95 | search_parser.add_argument("query", help="Search query") 96 | search_parser.add_argument("--source", help="Source name") 97 | 98 | # Get documentation 99 | get_parser = subparsers.add_parser("get", help="Test get documentation tool") 100 | get_parser.add_argument("source", help="Source name") 101 | get_parser.add_argument("document", help="Document name") 102 | get_parser.add_argument("--heading", help="Heading to retrieve") 103 | 104 | # Download documentation 105 | download_parser = subparsers.add_parser("download", help="Test download documentation tool") 106 | download_parser.add_argument("source", help="Source name") 107 | download_parser.add_argument("--url", help="URL to download from") 108 | 109 | # List documentation 110 | list_parser = subparsers.add_parser("list", help="Test list documentation tool") 111 | list_parser.add_argument("--source", help="Source name") 112 | 113 | args = parser.parse_args() 114 | 115 | if args.command == "search": 116 | asyncio.run(test_search_documentation(args.docs_dir, args.query, args.source)) 117 | elif args.command == "get": 118 | asyncio.run(test_get_documentation(args.docs_dir, args.source, args.document, args.heading)) 119 | elif args.command == "download": 120 | asyncio.run(test_download_documentation(args.docs_dir, args.source, args.url)) 121 | elif args.command == "list": 122 | asyncio.run(test_list_documentation(args.docs_dir, args.source)) 123 | else: 124 | parser.print_help() 125 | 126 | 127 | if __name__ == "__main__": 128 | main() -------------------------------------------------------------------------------- /docs/uv-backup/features_code-search.md: -------------------------------------------------------------------------------- 1 | Skip to content GitHub Copilot is now available for free. Learn more 2 | You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert 3 | {{ message }} 4 | Code Search 5 | # Exactly what you’re looking for 6 | With GitHub code search, your code—and the world’s—is at your fingertips. 7 | Try nowContact sales 8 | ![Screenshot of the GitHub code review interface displaying a repository's file structure and code editor. The left panel shows a file explorer with folders such as .github, .reuse, LICENSES, and library, with the wtf8.rs file currently open in the main editor. The code in the editor is written in Rust, defining a CodePoint struct and its related implementation. A search box at the bottom left shows search results for 'CodePoint' within the repository, listing various matches such as class CodePoint and implementation CodePoint. On the right side, a detailed symbol reference panel shows the definition of CodePoint and lists 24 references found in the code. The background features a gradient from green to teal, highlighting the focused and interactive nature of the code review process.](https://github.com/images/modules/site/code-search/fp24/hero.webp) 9 | ### Fast, relevant results 10 | Code search understands your code—and brings you relevant results with incredible speed. 11 | ### A power userʼs dream 12 | Search using regular expressions, boolean operations, keyboard shortcuts, and more. 13 | ### More than just search 14 | Dig deeper with the all-new code view—tightly integrating browsing and code navigation. 15 | **Suggestions, completions, and more.** Use the new search input to find symbols and files—and jump right to them. 16 | ![Screenshot showing the GitHub code search interface, with a search query for 'CodePoint' within the rust-lang/rust repository. The search results include various symbols and files related to 'CodePoint,' such as 'class CodePoint' in the library/wtf8.rs file, 'implementation CodePoint' in another file, and specific functions and fields like from_u32_unchecked and is_known_utf8. Each result has a 'Jump to' link on the right, allowing users to quickly navigate to the corresponding code. The background features a gradient from teal to green.](https://github.com/images/modules/site/code-search/fp24/features-river-1.webp) 17 | **Powerful search syntax.** Know exactly what you’re looking for? Express it with our powerful search operators. 18 | ![Screenshot of advanced GitHub search queries, including searches within the rust-lang organization, the tensorflow/tensorflow repository, and for 'validation' in Ruby or Python code. The background features a teal-to-green gradient.](https://github.com/images/modules/site/code-search/fp24/features-river-2.webp) 19 | **Code navigation.** Instantly jump to definitions in over 10 languages. No setup required. 20 | ![Screenshot of GitHub's code navigation panel showing details for the symbol CodePoint. It highlights the definition of CodePoint as a struct in the code and lists 24 references to it within the same file. The interface is dark-themed with a gradient background transitioning from green to blue.](https://github.com/images/modules/site/code-search/fp24/features-river-3.webp) 21 | **File browser.** Keep all your code in context and instantly switch files with the new file tree pane. 22 | ![Screenshot of the file explorer in GitHub's code interface, showing a directory structure. The main branch \(main\) is selected at the top. Folders like .github, .reuse, LICENSES, and library are visible, with the library folder expanded to reveal files such as backtrace.rs, condvar.rs, fs.rs, and wtf8.rs, with wtf8.rs currently selected. The background features a gradient from green to teal.](https://github.com/images/modules/site/code-search/fp24/features-river-4.webp) 23 | “ 24 | ![Circular avatar from Keith Smiley's GitHub profile](https://github.com/images/modules/site/code-search/fp24/testimonials-avatar-keith.jpg)Keith SmileySoftware Engineer 25 | “ 26 | ![Circular avatar from Marco Montagna's GitHub profile](https://github.com/images/modules/site/code-search/fp24/testimonials-avatar-marco.jpg)Marco MontagnaPlatform Engineer 27 | ### Find more, search less 28 | Try nowContact sales 29 | ### Frequently asked questions 30 | #### Do I need to set up my repositories to support code navigation? 31 | No, code navigation works out of the box, with zero configuration required. 32 | #### Who can search my code? 33 | Public code is searchable by anyone, but private code can only be searched by users who have access to it. 34 | #### How much does the new code search and code view cost? 35 | The new code search and code view are free for users of GitHub.com. 36 | You can’t perform that action at this time. 37 | -------------------------------------------------------------------------------- /docs/mcp_docs/docs_tools_inspector.md: -------------------------------------------------------------------------------- 1 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 2 | Search... 3 | ⌘K 4 | * Python SDK 5 | * TypeScript SDK 6 | * Java SDK 7 | * Kotlin SDK 8 | * Specification 9 | ##### Get Started 10 | * Introduction 11 | * Quickstart 12 | * Example Servers 13 | * Example Clients 14 | 15 | 16 | ##### Tutorials 17 | * Building MCP with LLMs 18 | * Debugging 19 | * Inspector 20 | 21 | 22 | ##### Concepts 23 | * Core architecture 24 | * Resources 25 | * Prompts 26 | * Tools 27 | * Sampling 28 | * Roots 29 | * Transports 30 | 31 | 32 | ##### Development 33 | * What's New 34 | * Roadmap 35 | * Contributing 36 | 37 | 38 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 39 | Search... 40 | ⌘K 41 | Search... 42 | Navigation 43 | Tutorials 44 | Inspector 45 | DocumentationSDKs 46 | DocumentationSDKs 47 | * GitHub 48 | The MCP Inspector is an interactive developer tool for testing and debugging MCP servers. While the Debugging Guide covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector’s features and capabilities. 49 | ## 50 | ​ 51 | Getting started 52 | ### 53 | ​ 54 | Installation and basic usage 55 | The Inspector runs directly through `npx` without requiring installation: 56 | Copy 57 | ``` 58 | npx @modelcontextprotocol/inspector 59 | 60 | ``` 61 | 62 | Copy 63 | ``` 64 | npx @modelcontextprotocol/inspector 65 | 66 | ``` 67 | 68 | #### 69 | ​ 70 | Inspecting servers from NPM or PyPi 71 | A common way to start server packages from NPM or PyPi. 72 | * NPM package 73 | * PyPi package 74 | 75 | 76 | Copy 77 | ``` 78 | npx -y @modelcontextprotocol/inspector npx 79 | # For example 80 | npx -y @modelcontextprotocol/inspector npx server-postgres postgres://127.0.0.1/testdb 81 | 82 | ``` 83 | 84 | #### 85 | ​ 86 | Inspecting locally developed servers 87 | To inspect servers locally developed or downloaded as a repository, the most common way is: 88 | * TypeScript 89 | * Python 90 | 91 | 92 | Copy 93 | ``` 94 | npx @modelcontextprotocol/inspector node path/to/server/index.js args... 95 | 96 | ``` 97 | 98 | Please carefully read any attached README for the most accurate instructions. 99 | ## 100 | ​ 101 | Feature overview 102 | ![](https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/mcp-inspector.png) 103 | The MCP Inspector interface 104 | The Inspector provides several features for interacting with your MCP server: 105 | ### 106 | ​ 107 | Server connection pane 108 | * Allows selecting the transport for connecting to the server 109 | * For local servers, supports customizing the command-line arguments and environment 110 | 111 | 112 | ### 113 | ​ 114 | Resources tab 115 | * Lists all available resources 116 | * Shows resource metadata (MIME types, descriptions) 117 | * Allows resource content inspection 118 | * Supports subscription testing 119 | 120 | 121 | ### 122 | ​ 123 | Prompts tab 124 | * Displays available prompt templates 125 | * Shows prompt arguments and descriptions 126 | * Enables prompt testing with custom arguments 127 | * Previews generated messages 128 | 129 | 130 | ### 131 | ​ 132 | Tools tab 133 | * Lists available tools 134 | * Shows tool schemas and descriptions 135 | * Enables tool testing with custom inputs 136 | * Displays tool execution results 137 | 138 | 139 | ### 140 | ​ 141 | Notifications pane 142 | * Presents all logs recorded from the server 143 | * Shows notifications received from the server 144 | 145 | 146 | ## 147 | ​ 148 | Best practices 149 | ### 150 | ​ 151 | Development workflow 152 | 1. Start Development 153 | * Launch Inspector with your server 154 | * Verify basic connectivity 155 | * Check capability negotiation 156 | 2. Iterative testing 157 | * Make server changes 158 | * Rebuild the server 159 | * Reconnect the Inspector 160 | * Test affected features 161 | * Monitor messages 162 | 3. Test edge cases 163 | * Invalid inputs 164 | * Missing prompt arguments 165 | * Concurrent operations 166 | * Verify error handling and error responses 167 | 168 | 169 | ## 170 | ​ 171 | Next steps 172 | ## Inspector Repository 173 | Check out the MCP Inspector source code 174 | ## Debugging Guide 175 | Learn about broader debugging strategies 176 | Was this page helpful? 177 | YesNo 178 | DebuggingCore architecture 179 | On this page 180 | * Getting started 181 | * Installation and basic usage 182 | * Inspecting servers from NPM or PyPi 183 | * Inspecting locally developed servers 184 | * Feature overview 185 | * Server connection pane 186 | * Resources tab 187 | * Prompts tab 188 | * Tools tab 189 | * Notifications pane 190 | * Best practices 191 | * Development workflow 192 | * Next steps 193 | 194 | 195 | -------------------------------------------------------------------------------- /docs/mcp_docs/index.md: -------------------------------------------------------------------------------- 1 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 2 | Search... 3 | ⌘K 4 | * Python SDK 5 | * TypeScript SDK 6 | * Java SDK 7 | * Kotlin SDK 8 | * Specification 9 | ##### Get Started 10 | * Introduction 11 | * Quickstart 12 | * Example Servers 13 | * Example Clients 14 | 15 | 16 | ##### Tutorials 17 | * Building MCP with LLMs 18 | * Debugging 19 | * Inspector 20 | 21 | 22 | ##### Concepts 23 | * Core architecture 24 | * Resources 25 | * Prompts 26 | * Tools 27 | * Sampling 28 | * Roots 29 | * Transports 30 | 31 | 32 | ##### Development 33 | * What's New 34 | * Roadmap 35 | * Contributing 36 | 37 | 38 | Model Context Protocol home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mcp/logo/dark.svg) 39 | Search... 40 | ⌘K 41 | Search... 42 | Navigation 43 | Get Started 44 | Introduction 45 | DocumentationSDKs 46 | DocumentationSDKs 47 | * GitHub 48 | Java SDK released! Check out what else is new. 49 | MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. 50 | ## 51 | ​ 52 | Why MCP? 53 | MCP helps you build agents and complex workflows on top of LLMs. LLMs frequently need to integrate with data and tools, and MCP provides: 54 | * A growing list of pre-built integrations that your LLM can directly plug into 55 | * The flexibility to switch between LLM providers and vendors 56 | * Best practices for securing your data within your infrastructure 57 | 58 | 59 | ### 60 | ​ 61 | General architecture 62 | At its core, MCP follows a client-server architecture where a host application can connect to multiple servers: 63 | * **MCP Hosts** : Programs like Claude Desktop, IDEs, or AI tools that want to access data through MCP 64 | * **MCP Clients** : Protocol clients that maintain 1:1 connections with servers 65 | * **MCP Servers** : Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol 66 | * **Local Data Sources** : Your computer’s files, databases, and services that MCP servers can securely access 67 | * **Remote Services** : External systems available over the internet (e.g., through APIs) that MCP servers can connect to 68 | 69 | 70 | ## 71 | ​ 72 | Get started 73 | Choose the path that best fits your needs: 74 | #### 75 | ​ 76 | Quick Starts 77 | ## For Server Developers 78 | Get started building your own server to use in Claude for Desktop and other clients 79 | ## For Client Developers 80 | Get started building your own client that can integrate with all MCP servers 81 | ## For Claude Desktop Users 82 | Get started using pre-built servers in Claude for Desktop 83 | #### 84 | ​ 85 | Examples 86 | ## Example Servers 87 | Check out our gallery of official MCP servers and implementations 88 | ## Example Clients 89 | View the list of clients that support MCP integrations 90 | ## 91 | ​ 92 | Tutorials 93 | ## Building MCP with LLMs 94 | Learn how to use LLMs like Claude to speed up your MCP development 95 | ## Debugging Guide 96 | Learn how to effectively debug MCP servers and integrations 97 | ## MCP Inspector 98 | Test and inspect your MCP servers with our interactive debugging tool 99 | ## MCP Workshop (Video, 2hr) 100 | ## 101 | ​ 102 | Explore MCP 103 | Dive deeper into MCP’s core concepts and capabilities: 104 | ## Core architecture 105 | Understand how MCP connects clients, servers, and LLMs 106 | ## Resources 107 | Expose data and content from your servers to LLMs 108 | ## Prompts 109 | Create reusable prompt templates and workflows 110 | ## Tools 111 | Enable LLMs to perform actions through your server 112 | ## Sampling 113 | Let your servers request completions from LLMs 114 | ## Transports 115 | Learn about MCP’s communication mechanism 116 | ## 117 | ​ 118 | Contributing 119 | Want to contribute? Check out our Contributing Guide to learn how you can help improve MCP. 120 | ## 121 | ​ 122 | Support and Feedback 123 | Here’s how to get help or provide feedback: 124 | * For bug reports and feature requests related to the MCP specification, SDKs, or documentation (open source), please create a GitHub issue 125 | * For discussions or Q&A about the MCP specification, use the specification discussions 126 | * For discussions or Q&A about other MCP open source components, use the organization discussions 127 | * For bug reports, feature requests, and questions related to Claude.app and claude.ai’s MCP integration, please email mcp-support@anthropic.com 128 | 129 | 130 | Was this page helpful? 131 | YesNo 132 | For Server Developers 133 | On this page 134 | * Why MCP? 135 | * General architecture 136 | * Get started 137 | * Quick Starts 138 | * Examples 139 | * Tutorials 140 | * Explore MCP 141 | * Contributing 142 | * Support and Feedback 143 | 144 | 145 | --------------------------------------------------------------------------------