aind-data-mcp 0.1.2__tar.gz

aind_data_mcp-0.1.2/LICENSE

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

aind_data_mcp-0.1.2/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: aind-data-mcp
+Version: 0.1.2
+Summary: Generated from aind-library-template
+Author: Allen Institute for Neural Dynamics
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aind-data-access-api
+Requires-Dist: fastmcp
+Requires-Dist: hdmf-zarr>=0.11.1
+Requires-Dist: langchain-core>=0.3.60
+Requires-Dist: pydantic>=2.11.4
+Requires-Dist: suffix-trees>=0.3.0
+Dynamic: license-file
+
+# AIND Data MCP Server
+
+[![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
+![Code Style](https://img.shields.io/badge/code%20style-black-black)
+[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
+![Interrogate](https://img.shields.io/badge/interrogate-100.0%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
+![Python](https://img.shields.io/badge/python->=3.11-blue?logo=python)
+
+An MCP (Model Context Protocol) server that provides access to AIND (Allen Institute for Neural Dynamics) metadata and data assets through a comprehensive set of tools and resources. This server targets the **V2 aind-data-schema** format.
+
+## Features
+
+This MCP server provides the following tools:
+
+**Data Retrieval & Querying**
+- `get_records` — Query MongoDB collections using filters and projections
+- `aggregation_retrieval` — Execute complex MongoDB aggregation pipelines
+- `count_records` — Count documents matching a filter
+- `flatten_records` — Retrieve and flatten records into dot-notation for easier inspection
+- `get_project_names` — List all project names in the database
+- `get_summary` — Generate an AI-powered summary for a specific data asset
+
+**Schema Navigation**
+- `get_top_level_nodes` — Explore the top-level fields of the V2 metadata schema
+- `get_additional_schema_help` — Query-writing guidance for V2 aggregations
+- `get_modality_types` — List all available data modality names and abbreviations
+
+**Schema Examples** (one tool per document type)
+- `get_acquisition_example`, `get_data_description_example`, `get_instrument_example`, `get_procedures_example`, `get_subject_example`, `get_processing_example`, `get_model_example`, `get_quality_control_example`
+
+**NWB File Access**
+- `identify_nwb_contents_in_code_ocean` — Load an NWB file from the `/data` directory in a Code Ocean capsule
+- `identify_nwb_contents_with_s3_link` — Load an NWB file from an S3 path
+
+**Resources** (accessible via the MCP protocol)
+- `resource://aind_api` — Context and usage patterns for the AIND data access API
+- `resource://load_nwbfile` — Reference script for loading NWB files
+
+## Installation
+
+Install uv if you haven't already — see [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).
+
+Install the MCP server using uv:
+
+```bash
+uv tool install aind-data-mcp
+```
+
+Or using pip:
+
+```bash
+pip install aind-data-mcp
+```
+
+## Configuration
+
+### For Cline (VSCode Extension)
+
+In order to ensure that the MCP server runs in your preferred client, you will have to download the `aind-data-mcp` package to your console. If space is an issue, please set `UV_CACHE_DIR` and `UV_TOOL_DIR` to locations that have capacity before proceeding with the next step.
+
+1. Simpler version of install
+   Run `uv tool install aind-data-mcp` on your terminal and proceed below to configuring your MCP clients.
+2. If the above step didn't work:
+
+Create virtual environment with python 3.11 in IDE
+
+```bash
+# Instructions for Conda
+conda create -n <my_env> python=3.11
+conda activate <my_env>
+
+# Instructions for virtual environment
+py -3.11 -m venv .venv
+# Windows startup
+.venv\Scripts\Activate.ps1
+# Mac/ Linux startup
+source .venv/bin/activate
+```
+
+Run the following commands in your IDE terminal.
+
+```bash
+pip install uv
+uvx aind-data-mcp
+```
+
+If all goes well, and you see the following notice - `Starting MCP server 'aind_data_mcp' with transport 'stdio'` -, you should be good for the set up in your client of choice!
+
+### Cursor IDE
+
+1. Install the MCP server:
+   ```bash
+   uv tool install aind-data-mcp
+   ```
+
+2. Create the MCP configuration file:
+   ```bash
+   mkdir -p ~/.cursor
+   ```
+
+3. Create `~/.cursor/mcp.json` with the following content:
+   ```json
+   {
+     "mcpServers": {
+       "aind-data-access": {
+         "command": "aind-data-mcp",
+         "args": [],
+         "env": {}
+       }
+     }
+   }
+   ```
+
+4. **Important**: Replace `aind-data-mcp` with the full path if needed:
+   ```bash
+   which aind-data-mcp
+   ```
+   Use the full path (e.g., `/Users/username/.local/bin/aind-data-mcp`) in the `command` field.
+
+5. Restart Cursor completely (Cmd+Q then reopen)
+
+**Note**: Cursor uses a different MCP configuration system than VSCode. The configuration must be in `~/.cursor/mcp.json`, not in the main settings.json file.
+
+## Instructions for use in MCP clients
+
+JSON Config files to add MCP servers in clients should be structured like this
+
+```json
+{
+    "mcpServers": {
+
+    }
+}
+```
+
+Insert the following lines into the mcpServers dictionary
+
+```json
+"aind_data_mcp": {
+      "disabled": false,
+      "timeout": 300,
+      "type": "stdio",
+      "command": "aind-data-mcp"
+}
+```
+
+Note that after configuring the JSON files, it will take a few minutes for the server to populate in the client.
+
+### Claude Desktop App
+
+- Click the three lines at the top left of the screen.
+- File > Settings > Developer > Edit config
+
+### Cline in VSCode
+
+- Ensure that Cline is downloaded to VSCode
+- Click the three stacked rectangles at the top right of the Cline window
+- Installed > Configure MCP Servers
+- Close and reopen VSCode
+
+### Github Copilot in VSCode
+
+- Command palette (ctrl shift p)
+- Search for MCP: Add server
+- Select `Manual Install` / `stdio`
+- When prompted for a command, input `uvx aind-data-mcp`
+- Name your server
+- Close and reopen VSCode
+- In Copilot chat -> Select agent mode -> Click the three stacked rectangles to configure tools
+- API context and NWB loading patterns are served automatically as MCP resources (`resource://aind_api` and `resource://load_nwbfile`) — no manual file setup required
+
+### For use in Code Ocean
+
+* Refer to the [code ocean MCP server](https://github.com/codeocean/codeocean-mcp-server) for additional support
+
+## Development
+
+To develop the code, run
+
+```bash
+uv sync --group dev
+```
+
+To run tests:
+
+```bash
+uv run coverage run -m unittest discover && uv run coverage report
+```
+
+To run linting:
+
+```bash
+uv run flake8 . && uv run interrogate --verbose .
+```

aind_data_mcp-0.1.2/README.md

@@ -0,0 +1,195 @@
+# AIND Data MCP Server
+
+[![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
+![Code Style](https://img.shields.io/badge/code%20style-black-black)
+[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
+![Interrogate](https://img.shields.io/badge/interrogate-100.0%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
+![Python](https://img.shields.io/badge/python->=3.11-blue?logo=python)
+
+An MCP (Model Context Protocol) server that provides access to AIND (Allen Institute for Neural Dynamics) metadata and data assets through a comprehensive set of tools and resources. This server targets the **V2 aind-data-schema** format.
+
+## Features
+
+This MCP server provides the following tools:
+
+**Data Retrieval & Querying**
+- `get_records` — Query MongoDB collections using filters and projections
+- `aggregation_retrieval` — Execute complex MongoDB aggregation pipelines
+- `count_records` — Count documents matching a filter
+- `flatten_records` — Retrieve and flatten records into dot-notation for easier inspection
+- `get_project_names` — List all project names in the database
+- `get_summary` — Generate an AI-powered summary for a specific data asset
+
+**Schema Navigation**
+- `get_top_level_nodes` — Explore the top-level fields of the V2 metadata schema
+- `get_additional_schema_help` — Query-writing guidance for V2 aggregations
+- `get_modality_types` — List all available data modality names and abbreviations
+
+**Schema Examples** (one tool per document type)
+- `get_acquisition_example`, `get_data_description_example`, `get_instrument_example`, `get_procedures_example`, `get_subject_example`, `get_processing_example`, `get_model_example`, `get_quality_control_example`
+
+**NWB File Access**
+- `identify_nwb_contents_in_code_ocean` — Load an NWB file from the `/data` directory in a Code Ocean capsule
+- `identify_nwb_contents_with_s3_link` — Load an NWB file from an S3 path
+
+**Resources** (accessible via the MCP protocol)
+- `resource://aind_api` — Context and usage patterns for the AIND data access API
+- `resource://load_nwbfile` — Reference script for loading NWB files
+
+## Installation
+
+Install uv if you haven't already — see [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).
+
+Install the MCP server using uv:
+
+```bash
+uv tool install aind-data-mcp
+```
+
+Or using pip:
+
+```bash
+pip install aind-data-mcp
+```
+
+## Configuration
+
+### For Cline (VSCode Extension)
+
+In order to ensure that the MCP server runs in your preferred client, you will have to download the `aind-data-mcp` package to your console. If space is an issue, please set `UV_CACHE_DIR` and `UV_TOOL_DIR` to locations that have capacity before proceeding with the next step.
+
+1. Simpler version of install
+   Run `uv tool install aind-data-mcp` on your terminal and proceed below to configuring your MCP clients.
+2. If the above step didn't work:
+
+Create virtual environment with python 3.11 in IDE
+
+```bash
+# Instructions for Conda
+conda create -n <my_env> python=3.11
+conda activate <my_env>
+
+# Instructions for virtual environment
+py -3.11 -m venv .venv
+# Windows startup
+.venv\Scripts\Activate.ps1
+# Mac/ Linux startup
+source .venv/bin/activate
+```
+
+Run the following commands in your IDE terminal.
+
+```bash
+pip install uv
+uvx aind-data-mcp
+```
+
+If all goes well, and you see the following notice - `Starting MCP server 'aind_data_mcp' with transport 'stdio'` -, you should be good for the set up in your client of choice!
+
+### Cursor IDE
+
+1. Install the MCP server:
+   ```bash
+   uv tool install aind-data-mcp
+   ```
+
+2. Create the MCP configuration file:
+   ```bash
+   mkdir -p ~/.cursor
+   ```
+
+3. Create `~/.cursor/mcp.json` with the following content:
+   ```json
+   {
+     "mcpServers": {
+       "aind-data-access": {
+         "command": "aind-data-mcp",
+         "args": [],
+         "env": {}
+       }
+     }
+   }
+   ```
+
+4. **Important**: Replace `aind-data-mcp` with the full path if needed:
+   ```bash
+   which aind-data-mcp
+   ```
+   Use the full path (e.g., `/Users/username/.local/bin/aind-data-mcp`) in the `command` field.
+
+5. Restart Cursor completely (Cmd+Q then reopen)
+
+**Note**: Cursor uses a different MCP configuration system than VSCode. The configuration must be in `~/.cursor/mcp.json`, not in the main settings.json file.
+
+## Instructions for use in MCP clients
+
+JSON Config files to add MCP servers in clients should be structured like this
+
+```json
+{
+    "mcpServers": {
+
+    }
+}
+```
+
+Insert the following lines into the mcpServers dictionary
+
+```json
+"aind_data_mcp": {
+      "disabled": false,
+      "timeout": 300,
+      "type": "stdio",
+      "command": "aind-data-mcp"
+}
+```
+
+Note that after configuring the JSON files, it will take a few minutes for the server to populate in the client.
+
+### Claude Desktop App
+
+- Click the three lines at the top left of the screen.
+- File > Settings > Developer > Edit config
+
+### Cline in VSCode
+
+- Ensure that Cline is downloaded to VSCode
+- Click the three stacked rectangles at the top right of the Cline window
+- Installed > Configure MCP Servers
+- Close and reopen VSCode
+
+### Github Copilot in VSCode
+
+- Command palette (ctrl shift p)
+- Search for MCP: Add server
+- Select `Manual Install` / `stdio`
+- When prompted for a command, input `uvx aind-data-mcp`
+- Name your server
+- Close and reopen VSCode
+- In Copilot chat -> Select agent mode -> Click the three stacked rectangles to configure tools
+- API context and NWB loading patterns are served automatically as MCP resources (`resource://aind_api` and `resource://load_nwbfile`) — no manual file setup required
+
+### For use in Code Ocean
+
+* Refer to the [code ocean MCP server](https://github.com/codeocean/codeocean-mcp-server) for additional support
+
+## Development
+
+To develop the code, run
+
+```bash
+uv sync --group dev
+```
+
+To run tests:
+
+```bash
+uv run coverage run -m unittest discover && uv run coverage report
+```
+
+To run linting:
+
+```bash
+uv run flake8 . && uv run interrogate --verbose .
+```

aind_data_mcp-0.1.2/pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aind-data-mcp"
+description = "Generated from aind-library-template"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [
+    {name = "Allen Institute for Neural Dynamics"}
+]
+classifiers = [
+    "Programming Language :: Python :: 3"
+]
+readme = "README.md"
+dynamic = ["version"]
+
+dependencies = [
+    "aind-data-access-api",
+    "fastmcp",
+    "hdmf-zarr>=0.11.1",
+    "langchain-core>=0.3.60",
+    "pydantic>=2.11.4",
+    "suffix-trees>=0.3.0",
+]
+
+[project.scripts]
+aind-data-mcp = "aind_data_mcp.data_access_server:main"
+
+[dependency-groups]
+dev = [
+    'black',
+    'coverage',
+    'flake8',
+    'interrogate',
+    'isort',
+    'Sphinx',
+    'furo'
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "aind_data_mcp.__version__"}
+
+[tool.black]
+line-length = 79
+target_version = ['py311']
+exclude = '''
+
+(
+  /(
+      \.eggs         # exclude a few common directories in the
+    | \.git          # root of the project
+    | \.hg
+    | \.mypy_cache
+    | \.tox
+    | \.venv
+    | _build
+    | build
+    | dist
+    | .conda
+  )/
+  | .gitignore
+)
+'''
+
+[tool.coverage.run]
+omit = ["*__init__*"]
+source = ["aind_data_mcp", "tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "if __name__ == .__main__.:",
+    "^from .* import .*",
+    "^import .*",
+    "pragma: no cover"
+]
+fail_under = 100
+
+[tool.isort]
+line_length = 79
+profile = "black"
+skip = [".conda"]
+
+[tool.interrogate]
+exclude = ["setup.py", "docs", "build", ".conda"]
+fail-under = 100

aind_data_mcp-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aind_data_mcp-0.1.2/src/aind_data_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""Init package"""
+__version__ = "0.1.2"

aind_data_mcp-0.1.2/src/aind_data_mcp/data_access_server.py

@@ -0,0 +1,42 @@
+"""MCP server for AIND data access."""
+
+from pathlib import Path
+
+# Import tool modules — side-effect registers all @mcp.tool() decorators
+from .mcp_instance import mcp  # noqa: F401
+from . import example_tools  # noqa: F401
+from . import nwb_tools  # noqa: F401
+from . import query_tools  # noqa: F401
+from . import schema_tools  # noqa: F401
+
+
+@mcp.resource("resource://aind_api")
+def get_aind_data_access_api() -> str:
+    """
+    Get context on how to use the AIND data access api to show users how to
+    wrap tool calls
+    """
+    resource_path = Path(__file__).parent / "resources" / "aind_api_prompt.txt"
+    with open(resource_path, "r") as file:
+        file_content = file.read()
+    return file_content
+
+
+@mcp.resource("resource://load_nwbfile")
+def get_nwbfile_download_script() -> str:
+    """
+    Get context on how to return an NWBfile from the /data folder in current repository
+    """
+    resource_path = Path(__file__).parent / "resources" / "load_nwbfile.txt"
+    with open(resource_path, "r") as file:
+        file_content = file.read()
+    return file_content
+
+
+def main():
+    """Main entry point for the MCP server."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()