CovAiLent

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

License: Apache-2.0 Python MCP

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.

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

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)

python -m mcp_server

Some environments may expect:

python -m mcp_server stdio

Run with MCP Inspector

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

Start the Inspector (Node.js required):
```
npx @modelcontextprotocol/inspector
```
In the UI, choose STDIO as transport and set the command to start this server:
```
python -m mcp_server
```
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):

{
  "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:

python examples/<example_name>.py

Development

Lint and test

pip install -r requirements.txt
# if available:
# make lint
# make test

Type checking

python -m pip install mypy
mypy mcp_server

HTTP/SSE (optional deployment)

If running with an HTTP app, for example:

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:

Fork the repository and create a feature branch.
Add tests or examples when appropriate.
Ensure linting and type checks pass.
Open a pull request with a clear description.