CovAiLent

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

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
• Features
• Architecture
• Quickstart
• Run with MCP Inspector
• Use with an MCP Host
• Configuration
• Repository Layout
• Examples
• Development
• Security Notes
• Roadmap
• Contributing
• 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

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.

1. Start the Inspector (Node.js required):

   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):

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

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 for details.