contextualizer-ai · turbomam · Jul 9, 2025 · Jul 9, 2025 · Jul 9, 2025 · Jul 9, 2025
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Justin Reese
+
+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.
diff --git a/README.md b/README.md
@@ -1,52 +1,247 @@
 # ols-mcp
 
-MCP for retrieving things from the Ontology Lookup  Service
+A Model Context Protocol (MCP) server for retrieving information from the Ontology Lookup Service (OLS). 
+
+This package provides tools for searching ontologies, retrieving ontology details, and accessing ontology terms through a standardized MCP interface.
 
 ## Installation
 
-You can install the package from source:
+### From PyPI
 
 ```bash
-pip install -e .
+pip install ols-mcp
 ```
 
-Or using uv:
+### From Source
 
 ```bash
-uv pip install -e .
+# Clone the repository
+git clone https://github.com/contextualizer-ai/ols-mcp.git
+cd ols-mcp
+
+# Install with uv (recommended)
+uv sync --group dev
+
+# Or with pip
+pip install -e .
 ```
 
 ## Usage
 
-You can use the CLI:
+### As MCP Server
+
+The primary use case is as an MCP server that provides ontology search capabilities to AI agents and applications.
+
+#### Claude Desktop Integration
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ols-mcp": {
+      "command": "ols-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+#### Claude Code Integration
 
 ```bash
-ols_mcp 
+claude mcp add ols-mcp
 ```
 
-Or import in your Python code:
+#### Goose Integration
+
+```bash
+goose session start --with-mcp "ols-mcp"
+```
+
+### Available Tools
+
+The MCP server provides three main tools:
+
+1. **`search_all_ontologies`** - Search across all ontologies in OLS
+2. **`get_ontology_info`** - Get detailed information about a specific ontology
+3. **`get_terms_from_ontology`** - Retrieve terms from a specific ontology
+
+### Direct Python Usage
 
 ```python
-from ols_mcp.main import create_mcp
+from ols_mcp.tools import search_all_ontologies, get_ontology_info, get_terms_from_ontology
+
+# Search for biological terms
+results = search_all_ontologies("apoptosis", max_results=5)
+
+# Get information about Gene Ontology
+go_info = get_ontology_info("go")
+
+# Get terms from a specific ontology
+terms = get_terms_from_ontology("go", max_results=10)
+```
+
+### CLI Usage
+
+#### Running the MCP Server
+
+Run the MCP server directly:
 
-mcp = create_mcp()
-mcp.run()
+```bash
+ols-mcp
+```
+
+#### Testing Individual Tools
+
+You can test the tools directly using Python:
+
+```bash
+# Search for biological terms across all ontologies
+uv run python -c "from ols_mcp.tools import search_all_ontologies; print(search_all_ontologies('apoptosis', max_results=3))"
+
+# Get information about Gene Ontology
+uv run python -c "from ols_mcp.tools import get_ontology_info; print(get_ontology_info('go'))"
+
+# Get terms from a specific ontology
+uv run python -c "from ols_mcp.tools import get_terms_from_ontology; print(get_terms_from_ontology('go', max_results=3))"
+```
+
+#### MCP Protocol Testing
+
+Test the MCP protocol directly:
+
+```bash
+# Test basic protocol handshake
+make test-mcp
+
+# Test extended protocol with tool calls
+make test-mcp-extended
 ```
 
 ## Development
 
-### Local Setup
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Setup
 
 ```bash
 # Clone the repository
-git clone https://github.com/justaddcoffee/ols-mcp.git
+git clone https://github.com/contextualizer-ai/ols-mcp.git
 cd ols-mcp
 
 # Install development dependencies
-uv pip install -e ".[dev]"
+uv sync --group dev
 ```
 
+### Available Make Targets
+
+#### Development
+- `make dev` - Install development dependencies
+- `make install` - Install production dependencies only
+- `make clean` - Clean build artifacts
+
+#### Testing
+- `make test-unit` - Run unit tests (fast, mocked)
+- `make test-real-api` - Run integration tests against live OLS API
+- `make test-mcp` - Test MCP protocol functionality
+
+#### Code Quality and Maintenance
+- `make format` - Format code with Black
+- `make lint` - Run Ruff linter with fixes
+- `make mypy` - Run type checking
+- `make deptry` - Check for unused dependencies
+- `make test-coverage` - Run all tests with coverage report
+- `make test-integration` - Run integration tests
+
+#### Build & Release
+- `make build` - Build package distributions
+- `make upload-test` - Upload to TestPyPI
+- `make upload` - Upload to PyPI
+- `make release` - Complete release workflow (test → build → upload)
+
+#### Server Operations
+- `make server` - Run the MCP server locally
+- `make all` - Run complete CI pipeline
+
+### Running Tests
+
+```bash
+# Run all tests
+make test-coverage
+
+# Run only unit tests (fast)
+make test-unit
+
+# Run integration tests against real OLS API
+make test-real-api
+
+# Run with specific pytest options
+uv run pytest tests/ -v -k "test_search"
+```
+
+#### Code Quality Tools
+
+The project uses modern Python tooling:
+
+- **uv** - Fast Python package manager
+- **ruff** - Fast Python linter and formatter
+- **black** - Code formatting (alternative to ruff format)
+- **mypy** - Static type checking
+- **pytest** - Testing framework with coverage reporting
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run the test suite: `make all`
+5. Submit a pull request
+
+### Release Process
+
+Releases are automated via GitHub Actions:
+
+1. Create and push a version tag:
+   ```bash
+   git tag v0.1.4
+   git push origin v0.1.4
+   ```
+
+2. GitHub Actions will automatically:
+   - Run the full test suite
+   - Build the package
+   - Publish to PyPI
+
+## Architecture
+
+### Project Structure
+
+```
+ols-mcp/
+├── src/ols_mcp/
+│   ├── __init__.py
+│   ├── main.py          # FastMCP server setup
+│   ├── api.py           # OLS API wrapper functions
+│   └── tools.py         # MCP tools that wrap API functions
+├── tests/
+│   ├── test_api.py      # Unit tests for API functions
+│   ├── test_tools.py    # Unit tests for MCP tools
+│   └── test_integration.py # Integration tests with real OLS API
+├── .github/workflows/   # CI/CD pipelines
+├── Makefile            # Development automation
+└── pyproject.toml      # Project configuration
+```
+
+### Key Components
+
+- **`api.py`** - Low-level functions that interact with OLS REST API
+- **`tools.py`** - Higher-level MCP tools that provide simplified interfaces
+- **`main.py`** - FastMCP server that exposes tools via MCP protocol
 
 ## License
 
-BSD-3-Clause
+MIT
diff --git a/pyproject.toml b/pyproject.toml
@@ -8,7 +8,8 @@ dynamic = ["version"]
 description = "MCP for retrieving things from the Ontology Lookup Service"
 readme = "README.md"
 requires-python = ">=3.11"
-license = {text = "MIT"}
+license = {file = "LICENSE"}
+license-expression = "MIT"
 authors = [
     {name = "Justin Reese", email = "justinreese@lbl.gov"},
 ]
@@ -75,6 +76,7 @@ include = [
     "src",
     "tests",
     "README.md",
+    "LICENSE",
     "pyproject.toml",
 ]