# CovAiLent  
_A Model Context Protocol (MCP) server for chemistry-focused tools with a focus on autonomy and explainability._

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%2B-informational.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-server-brightgreen)](https://modelcontextprotocol.io/)

CovAiLent provides chemistry-related operations over the **Model Context Protocol (MCP)** so clients can query, transform, and reason about molecular information in a structured way.

---

## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Architecture](#architecture)
- [Quickstart](#quickstart)
- [Run with MCP Inspector](#run-with-mcp-inspector)
- [Use with an MCP Host](#use-with-an-mcp-host)
- [Configuration](#configuration)
- [Repository Layout](#repository-layout)
- [Examples](#examples)
- [Development](#development)
- [Security Notes](#security-notes)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)

---

## Overview
Large language model agents often need domain-specific operations such as parsing molecules, converting formats, looking up properties, or planning laboratory tasks. CovAiLent exposes these operations through MCP, making them:
- **Composable**: usable from any MCP-compatible client or multi-agent framework.
- **Auditable**: responses return structured outputs with optional explanations.
- **Portable**: implemented in Python and can run locally or behind HTTPS/SSE.

---

## Features
- Exposes chemistry operations as typed MCP tools with JSON-schema input and output.
- Provides resources such as reference data as MCP resources.
- Supports explainability options in responses.
- Offers multiple transports: STDIO for local use, HTTP(S)/SSE for deployment.
- Includes runnable examples and helper scripts.

---

## Architecture
```
mcp_client (host/app)
        │
        ├── STDIO  (local development)
        └── HTTP/SSE (remote/self-hosted)
                │
          ┌─────┴─────────────────────────────┐
          │           CovAiLent MCP Server    │
          │  • Tools: chemistry operations    │
          │  • Resources: reference data      │
          │  • Explainability: optional notes │
          └───────────────────────────────────┘
```

---

## Quickstart

### Prerequisites
- Python **3.10+**
- A virtual environment tool (`venv`, `uv`, or `conda`)
- Node.js (required if you use the MCP Inspector UI)

### 1) Clone and install
```bash
git clone https://github.com/Mod26y/CovAiLent.git
cd CovAiLent
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

### 2) Run the server (STDIO)
```bash
python -m mcp_server
```
Some environments may expect:
```bash
python -m mcp_server stdio
```

---

## Run with MCP Inspector
The MCP Inspector helps explore CovAiLent’s tools and schemas.

1. Start the Inspector (Node.js required):
   ```bash
   npx @modelcontextprotocol/inspector
   ```
2. In the UI, choose **STDIO** as transport and set the command to start this server:
   ```
   python -m mcp_server
   ```
3. Connect and view the **Tools** tab to run CovAiLent tools.

---

## Use with an MCP Host
Add CovAiLent as a custom MCP server in your host configuration. Example for Claude Desktop (`claude_desktop_config.json`):

```jsonc
{
  "mcpServers": {
    "covailent": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "env": {
        // Optional: API keys or feature flags
        // "COVAILENT_API_KEY": "...",
        // "COVAILENT_ENABLE_EXPLANATIONS": "1"
      }
    }
  }
}
```

---

## Configuration
Environment variables supported at startup include:

| Variable | Purpose |
|---|---|
| `COVAILENT_ENABLE_EXPLANATIONS` | Include human-readable rationales in responses. |
| `COVAILENT_DEFAULT_TIMEOUT_MS` | Per-tool timeout in milliseconds. |
| `HTTP_PORT` / `HOST` | If running the HTTP/SSE server. |
| `LOG_LEVEL` | One of `DEBUG, INFO, WARNING, ERROR`. |

---

## Repository Layout

```
.
├─ mcp_server/     # Server code (tools, resources, transports)
├─ examples/       # Demonstrations and scripts
├─ scripts/        # Development and helper scripts
├─ requirements.txt
├─ LICENSE         # Apache-2.0
└─ README.md
```

---

## Examples
See `examples/` for end-to-end demonstrations:
- Tool discovery and execution
- Format conversion between chemical representations
- Property lookups and calculations
- Explainable responses

Run an example:
```bash
python examples/<example_name>.py
```

---

## Development

### Lint and test
```bash
pip install -r requirements.txt
# if available:
# make lint
# make test
```

### Type checking
```bash
python -m pip install mypy
mypy mcp_server
```

### HTTP/SSE (optional deployment)
If running with an HTTP app, for example:
```bash
uvicorn mcp_server.http:app --host 127.0.0.1 --port 8765
```

---

## Security Notes
- MCP servers execute tools at request time. Run CovAiLent in a restricted environment and validate inputs.  
- When exposing over HTTP/SSE, use authentication and restrict origins.  
- Periodic security reviews are recommended before integrating into production agents.

---

## Roadmap
- Additional chemistry tools and dataset resources
- Extended explainability options (structured traces)
- Provider integrations via environment variables
- Docker image for deployment

---

## Contributing
Please open an issue to discuss proposed features or bug fixes before submitting a PR. The process is:
1. Fork the repository and create a feature branch.
2. Add tests or examples when appropriate.
3. Ensure linting and type checks pass.
4. Open a pull request with a clear description.

---

## License
Apache License 2.0 © CovAiLent contributors. See [LICENSE](LICENSE) for details.