first-agentic-csa 0.2.0__py3-none-any.whl

first_agentic_csa-0.2.0.dist-info/METADATA

@@ -0,0 +1,409 @@
+Metadata-Version: 2.4
+Name: first-agentic-csa
+Version: 0.2.0
+Summary: Plugin-based FRC documentation agent as an MCP server for WPILib and vendor libraries
+Author: Rami Mouro
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: csa,documentation,first,frc,mcp,robotics,wpilib
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: lxml>=5.0.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: rank-bm25>=0.2.2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FIRST Agentic CSA
+
+A plugin-based FRC documentation agent implemented as a Model Context Protocol (MCP) server. Search across WPILib and vendor documentation (REV, CTRE, Redux, PhotonVision) using natural language queries. Built for FIRST Robotics Competition teams and CSAs (Control System Advisors).
+
+## Features
+
+- **Unified Search**: Query WPILib + vendor docs with a single tool
+- **Plugin Architecture**: Extensible system for adding new documentation sources
+- **BM25 Ranking**: High-quality text search without embedding costs
+- **Multi-Vendor Support**: WPILib, REV Robotics, CTRE Phoenix, Redux Robotics, PhotonVision
+- **Language Filtering**: Filter results by Java, Python, or C++
+- **Version Support**: Search specific documentation versions (2024, 2025, etc.)
+
+## Installation
+
+### Quick Install (PyPI)
+
+```bash
+# Using uvx (recommended)
+uvx first-agentic-csa
+
+# Or with pip
+pip install first-agentic-csa
+```
+
+### From Source
+
+If you want to modify or contribute to the project:
+
+1. **Install uv** (fast Python package manager):
+
+   **Windows (PowerShell):**
+   ```powershell
+   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+   ```
+
+   **macOS/Linux:**
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+2. **Clone and install:**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/first-agentic-csa.git
+   cd first-agentic-csa
+   uv sync
+   ```
+
+## Quick Start
+
+### Running the Server
+
+```bash
+# With uv
+uv run first-agentic-csa
+
+# Or directly
+python -m wpilib_mcp.server
+```
+
+### Configure in Claude Desktop / Cursor
+
+Add to your MCP configuration (`claude_desktop_config.json` or Cursor settings):
+
+```json
+{
+  "mcpServers": {
+    "frc-docs": {
+      "command": "uvx",
+      "args": ["first-agentic-csa"]
+    }
+  }
+}
+```
+
+If running from source:
+```json
+{
+  "mcpServers": {
+    "frc-docs": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/first-agentic-csa", "run", "first-agentic-csa"]
+    }
+  }
+}
+```
+
+### Configure in Other MCP Clients
+
+The server uses stdio transport and is compatible with any MCP client.
+
+## Available Tools
+
+### `search_frc_docs`
+
+Search FRC documentation across WPILib and vendor libraries.
+
+```
+query: "SparkMax configure"
+vendors: ["all"] | ["wpilib", "rev", "ctre", "redux"]
+version: "2025"
+language: "Java" | "Python" | "C++"
+max_results: 1-25
+```
+
+### `fetch_frc_doc_page`
+
+Fetch the full content of a documentation page by URL.
+
+```
+url: "https://docs.wpilib.org/en/stable/docs/software/commandbased/commands.html"
+```
+
+### `list_frc_doc_sections`
+
+List available documentation sections from vendors.
+
+```
+vendors: ["all"] | ["wpilib", "rev"]
+version: "2025"
+language: "Java"
+```
+
+## Configuration
+
+Edit `config.json` to customize plugin settings:
+
+```json
+{
+  "plugins": {
+    "wpilib": {
+      "enabled": true,
+      "versions": ["2025"],
+      "languages": ["Java", "Python", "C++"]
+    },
+    "rev": {
+      "enabled": true,
+      "languages": ["Java", "C++"]
+    },
+    "ctre": {
+      "enabled": false
+    }
+  },
+  "cache": {
+    "ttl_seconds": 3600
+  },
+  "search": {
+    "default_max_results": 10,
+    "default_language": "Java"
+  }
+}
+```
+
+## Supported Plugins
+
+| Plugin | Vendor | Documentation |
+|--------|--------|---------------|
+| `wpilib` | WPILib | docs.wpilib.org |
+| `rev` | REV Robotics | docs.revrobotics.com |
+| `ctre` | CTRE Phoenix | v6.docs.ctr-electronics.com |
+| `redux` | Redux Robotics | docs.reduxrobotics.com |
+| `photonvision` | PhotonVision | docs.photonvision.org |
+
+## Building Documentation Indexes
+
+Each plugin has its own index builder that vendors can maintain independently.
+
+### Using the convenience wrapper:
+
+```bash
+# Build all plugin indexes
+python scripts/build_index.py all
+
+# Build specific vendor
+python scripts/build_index.py wpilib --version 2025
+python scripts/build_index.py rev
+python scripts/build_index.py ctre
+```
+
+### Running plugin builders directly:
+
+```bash
+# Each plugin has its own build_index.py with vendor-specific options
+python -m wpilib_mcp.plugins.wpilib.build_index --version stable --verbose
+python -m wpilib_mcp.plugins.rev.build_index --verbose
+python -m wpilib_mcp.plugins.ctre.build_index --version stable
+python -m wpilib_mcp.plugins.redux.build_index
+```
+
+## Plugin Development
+
+Create a new plugin by following this structure:
+
+```
+plugins/
+└── myplugin/
+    ├── __init__.py
+    ├── plugin.py        # Must export `Plugin` class
+    ├── build_index.py   # Index builder script (vendor-maintained)
+    └── data/
+        └── index.json
+```
+
+Your `Plugin` class must implement `PluginBase`, and you should provide a `build_index.py` script:
+
+### Plugin Implementation
+
+Your `Plugin` class must implement `PluginBase`:
+
+```python
+from wpilib_mcp.plugins.base import PluginBase, PluginConfig, SearchResult, PageContent, DocSection
+
+class Plugin(PluginBase):
+    @property
+    def name(self) -> str:
+        return "myplugin"
+    
+    @property
+    def display_name(self) -> str:
+        return "My Plugin"
+    
+    @property
+    def description(self) -> str:
+        return "Description of my plugin"
+    
+    @property
+    def supported_versions(self) -> list[str]:
+        return ["2025"]
+    
+    @property
+    def supported_languages(self) -> list[str]:
+        return ["Java", "Python"]
+    
+    @property
+    def base_urls(self) -> list[str]:
+        return ["https://docs.example.com"]
+    
+    async def initialize(self, config: PluginConfig) -> None:
+        # Load index, build search corpus
+        pass
+    
+    async def search(self, query, version=None, language=None, max_results=10) -> list[SearchResult]:
+        # Return search results
+        pass
+    
+    async def fetch_page(self, url) -> PageContent:
+        # Fetch and clean page content
+        pass
+    
+    async def list_sections(self, version=None, language=None) -> list[DocSection]:
+        # Return documentation sections
+        pass
+```
+
+### Index Builder
+
+Create a `build_index.py` that extends `BaseIndexBuilder`:
+
+```python
+from wpilib_mcp.utils.indexer import BaseIndexBuilder
+
+class MyPluginIndexBuilder(BaseIndexBuilder):
+    def __init__(self):
+        super().__init__(
+            vendor="myplugin",
+            base_url="https://docs.example.com",
+            max_pages=200,
+        )
+    
+    @property
+    def start_urls(self) -> list[str]:
+        return ["https://docs.example.com/getting-started"]
+    
+    def should_crawl(self, url: str) -> bool:
+        return "docs.example.com" in url
+    
+    def extract_section(self, soup, url) -> str:
+        # Return section name based on URL/content
+        return "General"
+    
+    def extract_language(self, soup, url) -> str:
+        return "All"
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(MyPluginIndexBuilder().build_and_save("latest", Path("data/index.json")))
+```
+
+## Index File Format
+
+Each plugin uses a JSON index with this structure:
+
+```json
+{
+  "vendor": "myplugin",
+  "version": "2025",
+  "built_at": "2025-01-15T00:00:00Z",
+  "pages": [
+    {
+      "url": "https://docs.example.com/page",
+      "title": "Page Title",
+      "section": "Section Name",
+      "language": "Java",
+      "content": "Full searchable content...",
+      "content_preview": "First 300 chars for display..."
+    }
+  ]
+}
+```
+
+## Development
+
+### Running Tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+### Project Structure
+
+```
+wpilib-mcp/
+├── pyproject.toml          # Project configuration
+├── config.json             # User configuration
+├── src/wpilib_mcp/
+│   ├── server.py           # MCP server entry point
+│   ├── plugin_loader.py    # Plugin discovery/loading
+│   ├── tool_router.py      # Routes tools to plugins
+│   ├── utils/
+│   │   ├── fetch.py        # HTTP with caching
+│   │   ├── html.py         # HTML cleaning
+│   │   └── search.py       # BM25 search
+│   └── plugins/
+│       ├── base.py         # Plugin base class
+│       ├── wpilib/         # WPILib plugin
+│       ├── rev/            # REV plugin
+│       ├── ctre/           # CTRE plugin
+│       └── redux/          # Redux plugin
+├── scripts/
+│   └── build_index.py      # Index builder script
+└── tests/
+    ├── test_search.py
+    └── test_plugins.py
+```
+
+## Example Queries
+
+**Finding Command-Based Programming docs:**
+```
+search_frc_docs(query="command based programming subsystems", vendors=["wpilib"])
+```
+
+**Comparing motor controllers:**
+```
+search_frc_docs(query="SparkMax configuration", vendors=["rev"])
+search_frc_docs(query="TalonFX configuration", vendors=["ctre"])
+```
+
+**Looking up specific hardware:**
+```
+search_frc_docs(query="CANcoder absolute position swerve", vendors=["ctre"])
+search_frc_docs(query="through bore encoder", vendors=["rev"])
+```
+
+**Cross-vendor search:**
+```
+search_frc_docs(query="brushless motor closed loop velocity control", vendors=["all"])
+```
+
+## License
+
+BSD-3-Clause License - see LICENSE file for details.
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Add tests for new functionality
+3. Submit a pull request
+
+For new vendor plugins, please include:
+- Complete plugin implementation
+- Pre-built index file
+- Documentation updates

first_agentic_csa-0.2.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+wpilib_mcp/__init__.py,sha256=cXMssSHAC_SUiHYnlu72IfcPZIxeUxegAkDAG06oIp0,91
+wpilib_mcp/plugin_loader.py,sha256=nCmRpVEs2zv7_F_ptV4DgJCNxNSuJJUWoivwA62AkDo,8962
+wpilib_mcp/server.py,sha256=fhk_gP1VIGYBho6UOqgdI41I0xohIydZA-XF3nRNsE4,10951
+wpilib_mcp/tool_router.py,sha256=3Fca3Z4BiHq7ipP7wZQi-rfGn4wKz1fx0Uwwcvdroj4,9963
+wpilib_mcp/plugins/__init__.py,sha256=6NYhvOIhx1Q5MIkLLQDcQJo0uK3ezOoOQOG-dTNL9xk,187
+wpilib_mcp/plugins/base.py,sha256=OTZSJtlJjo3oKvpLkj9G_y_Hw-Oe2Y7QuRusNK0sxdQ,7002
+wpilib_mcp/plugins/ctre/__init__.py,sha256=dse6ZjgP_ovuxP_1R8vsNNt3hyfy7NpHhbY7IQtOvok,95
+wpilib_mcp/plugins/ctre/build_index.py,sha256=rFtcKFLLN-DI5cjRh5luNvd-jUeIkxhtGCRRFYY5p24,6039
+wpilib_mcp/plugins/ctre/plugin.py,sha256=41B-352tG12nuR8NYxdwWWkwH2yRy1aCvIbvDxEHP38,7869
+wpilib_mcp/plugins/ctre/data/index.json,sha256=ftTCa-FEBREwjnYkDm4NRsnEzg5cRBEBCtkZVou-AWs,434350
+wpilib_mcp/plugins/photonvision/__init__.py,sha256=B4N75yF0wp4kumBaCS9T-dmUZU4PZMQ1yMoVlIMpJpo,92
+wpilib_mcp/plugins/photonvision/build_index.py,sha256=numVCFBv9BpY08DPla6kzAYKpoNYtsl3eT2vxnCN1Nk,8932
+wpilib_mcp/plugins/photonvision/plugin.py,sha256=BCceXXnpka7c1AIOlgzXe_6RNIhGLyGzUXUPmNICXOY,7833
+wpilib_mcp/plugins/photonvision/data/index.json,sha256=7zMO1yQGvuSwqUmGMEZpJhWcmOMj7V-hiBHTpRMHbcs,247612
+wpilib_mcp/plugins/redux/__init__.py,sha256=ioq3E6okUy_P0_6LHKUZqwE0dWoUXCWBh9pYkkUzC6U,97
+wpilib_mcp/plugins/redux/build_index.py,sha256=fpIbcipFhoYuL30h7iyF1oxjKQEKTzZqO4wjKDQAjf8,4895
+wpilib_mcp/plugins/redux/plugin.py,sha256=1BVv1k5RIzGc-2udonZwVLeXdDZ1IotZnOMHYV1qYIs,7812
+wpilib_mcp/plugins/redux/data/index.json,sha256=XANxS_HbVxsd5msGZ6HCh1hprNBw8cvlj_gWGZSrRYQ,98370
+wpilib_mcp/plugins/rev/__init__.py,sha256=hrP4mZFfP_DsWoIoAk9pc8JosavHwEioWJYcPvxr17g,95
+wpilib_mcp/plugins/rev/build_index.py,sha256=nqQV9RRGi5AHQU0_EHjR-ffaxSKl8Y7TPuG9lN5Ihqg,5703
+wpilib_mcp/plugins/rev/plugin.py,sha256=7oZavjIBA8miWBFU97myH0oznu-VYmPWYZijSVtm1nA,7765
+wpilib_mcp/plugins/rev/data/index.json,sha256=h-mzM-trfe82LL8TzIsg5YwvYlzyJ5zzd1ZpZ-mZaQQ,210040
+wpilib_mcp/plugins/wpilib/__init__.py,sha256=G86KSRIPuOma2PGEBjmomLZFplzq4nCLo9xpp9fHA8Y,89
+wpilib_mcp/plugins/wpilib/build_index.py,sha256=jw8-xJzAhtWxI_Oo6kdQoqteOeNiOtTT1y4slqbQ2gY,6684
+wpilib_mcp/plugins/wpilib/plugin.py,sha256=lwZ5D80gXqX2M8_QYtDbckeMrWiJYUDqBDQQ3eCqNVE,8778
+wpilib_mcp/plugins/wpilib/data/index_2025.json,sha256=wqs95sPACYzvvpEKEC6-leROBd0_mnnVMmaekXoeqEw,17386
+wpilib_mcp/plugins/wpilib/data/index_stable.json,sha256=q1QCOoj8Xa1Vm1QO0xU9jps410SAVvoZrCm1jIh7gaA,1927785
+wpilib_mcp/utils/__init__.py,sha256=sGGqwgbMNR8emv9vxsc-nhs1G2yLDa6XGXEYk5r51vk,286
+wpilib_mcp/utils/fetch.py,sha256=zSsXFoo2dWJDpkKBHzcvSFobwRdktQEdoPtbHoxl-io,4640
+wpilib_mcp/utils/html.py,sha256=uy1OXkoE9s7tRqA-Oc1VIGgF4V2s9XJiuxypSLbFapQ,8955
+wpilib_mcp/utils/indexer.py,sha256=MncZslFy51gDf8G5esn8soGoK_6_gQ28XbFOHqmF2E0,9675
+wpilib_mcp/utils/search.py,sha256=_KZgi_1n-dwLTO6JXXPizkfkdxBLoT0Y4YH_IoCexU4,6058
+first_agentic_csa-0.2.0.dist-info/METADATA,sha256=fF_mZ681CpbEm61cooO7-7jUCOgbNxPQrut0u9laS_U,10183
+first_agentic_csa-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+first_agentic_csa-0.2.0.dist-info/entry_points.txt,sha256=H9utHQ6kCQhVqoP10Ap3qUeMzUivFzFbhCScpjvKpec,61
+first_agentic_csa-0.2.0.dist-info/licenses/LICENSE,sha256=EzfGZ7xpAEI8h-ZU9KjGNt8ny2mTCTMTC0WexTh5xXo,1497
+first_agentic_csa-0.2.0.dist-info/RECORD,,

first_agentic_csa-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

first_agentic_csa-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+first-agentic-csa = wpilib_mcp.server:main

first_agentic_csa-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Rami Mouro
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

wpilib_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""WPILib MCP Server - Plugin-based FRC documentation agent."""
+
+__version__ = "0.1.0"
+
+
+
+