rosetta-mcp

Model Context Protocol (MCP) server for Rosetta (Enterprise Engineering Governance and Instructions Management System)

Powered by RAGFlow for advanced RAG capabilities

This package provides a FastMCP server that connects to Rosetta servers for advanced retrieval-augmented generation (RAG) capabilities. It enables AI assistants like Claude Desktop, Cursor, and other MCP clients to search, retrieve, and manage documents in Rosetta knowledge bases.

Community

• Website
• rosetta-support@griddynamics.com

Features

• 🧭 Context Bootstrap - get_context_instructions loads bootstrap rules for agent setup
• 📚 Instruction Retrieval - query_instructions fetches docs by keyword or tags
• 🗂️ Instruction Browsing - list_instructions lists folders/files by virtual path prefix
• 🔗 Instruction Resources - rosetta://{path*} resource template for bundled reads
• 🌐 Environment-Based Config - Zero configuration, reads from environment variables
• 🔐 STDIO + HTTP OAuth - API-key runtime plus OAuth proxy support for HTTP transports
• 📊 Usage Analytics - Built-in PostHog integration for tracking feature adoption (enabled by default, opt-out)

Installation

Using uvx (recommended)

The easiest way to use rosetta-mcp is with uvx, which automatically handles installation:

uvx rosetta-mcp@latest

Using pip

Install globally or in a virtual environment:

pip install rosetta-mcp

Then run:

rosetta-mcp

As a Python Module

You can also run it as a module:

python -m rosetta_mcp

Configuration

Rosetta MCP supports two runtime modes:

1. STDIO (default) for MCP clients that launch a local process (command + args)
2. HTTP for remote/server deployment behind OAuth

Complete Environment Variable Reference

Shared Variables (Both Modes)

STDIO Mode (Default)

Set:

ROSETTA_TRANSPORT=stdio

STDIO keeps API-key access and does not use OAuth. User identity for authorization checks comes from:

ROSETTA_USER_EMAIL=rosetta@example.com

HTTP Mode

Set:

ROSETTA_TRANSPORT=http
ROSETTA_HTTP_HOST=0.0.0.0
ROSETTA_HTTP_PORT=8000

Optional HTTP runtime settings:

OAuth variables for HTTP mode:

Authorization policy variables:

OAuth callback URL examples:

• Production: https://rosetta.example.com/auth/callback
• Local: http://localhost:8000/auth/callback

Usage with MCP Clients

STDIO Mode (Cursor / Claude / local MCP clients)

Add to .cursor/mcp.json (or equivalent client config):

{
  "mcpServers": {
    "Rosetta": {
      "command": "uvx",
      "args": ["rosetta-mcp@latest"],
      "env": {
        "ROSETTA_TRANSPORT": "stdio",
        "ROSETTA_SERVER_URL": "https://<production server URL>",
        "ROSETTA_API_KEY": "your-rosetta-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

HTTP Mode (Server deployment)

Start Rosetta MCP in HTTP mode:

ROSETTA_TRANSPORT=http \
ROSETTA_SERVER_URL="https://<production server URL>" \
ROSETTA_API_KEY="your-rosetta-api-key" \
ROSETTA_HTTP_HOST=0.0.0.0 \
ROSETTA_HTTP_PORT=8000 \
ROSETTA_OAUTH_AUTHORIZATION_ENDPOINT="https://idp.example.com/realms/<realm>/protocol/openid-connect/auth" \
ROSETTA_OAUTH_TOKEN_ENDPOINT="https://idp.example.com/realms/<realm>/protocol/openid-connect/token" \
ROSETTA_OAUTH_INTROSPECTION_ENDPOINT="https://idp.example.com/realms/<realm>/protocol/openid-connect/token/introspect" \
ROSETTA_OAUTH_CLIENT_ID="<client-id>" \
ROSETTA_OAUTH_CLIENT_SECRET="<client-secret>" \
ROSETTA_OAUTH_BASE_URL="https://rosetta.example.com" \
rosetta-mcp

For multi-instance deployment with shared session state, add REDIS_URL:

ROSETTA_TRANSPORT=http \
ROSETTA_SERVER_URL="https://<production server URL>" \
ROSETTA_API_KEY="your-rosetta-api-key" \
ROSETTA_HTTP_HOST=0.0.0.0 \
ROSETTA_HTTP_PORT=8000 \
REDIS_URL="redis://localhost:6379/0" \
ROSETTA_OAUTH_AUTHORIZATION_ENDPOINT="https://idp.example.com/realms/<realm>/protocol/openid-connect/auth" \
ROSETTA_OAUTH_TOKEN_ENDPOINT="https://idp.example.com/realms/<realm>/protocol/openid-connect/token" \
ROSETTA_OAUTH_INTROSPECTION_ENDPOINT="https://idp.example.com/realms/<realm>/protocol/openid-connect/token/introspect" \
ROSETTA_OAUTH_CLIENT_ID="<client-id>" \
ROSETTA_OAUTH_CLIENT_SECRET="<client-secret>" \
ROSETTA_OAUTH_BASE_URL="https://rosetta.example.com" \
rosetta-mcp

If your MCP client supports HTTP servers directly, point it to:

http://<host>:<port>/mcp

Minimal HTTP client config shape (client-specific fields may vary):

{
  "mcpServers": {
    "RosettaHTTP": {
      "url": "<rosetta MCP production server URL>"
    }
  }
}

Available MCP Tools

1. get_context_instructions

Load bootstrap context instructions (prep step entry point).

Parameters:

• topic (str, optional): Brief intent summary (<=10 words), used for tracking only

Example:

get_context_instructions(topic="update readme")

2. query_instructions

Fetch instruction documents from the instruction dataset.

Parameters:

• query (str, optional): Keyword query
• tags (list[str], optional): Tag-based query (OR logic)
• topic (str, optional): Tracking-only intent hint

At least one of query or tags is required.

Validation notes:

• query: up to 2000 characters
• tags: up to 50 items, each up to 128 characters
• single-string tags input must be non-empty

Example:

query_instructions(tags=["bootstrap"])

3. list_instructions

List immediate children under a virtual instruction path without loading file content.

Parameters:

• full_path_from_root (str): Virtual path prefix such as skills, rules, or workflows, or all to list all instruction files without content

Validation notes:

• Use "" or / to list the root
• Use all to list all <rosetta:file /> entries without content
• all includes a note that duplicate path values are bundled/combined when acquired
• Use guaranteed unique 3-part/2-part tags to read specific content
• full_path_from_root must stay relative
• full_path_from_root must not contain . or .. path segments
• max length: 512 characters

Example:

list_instructions(full_path_from_root="rules")
list_instructions(full_path_from_root="all")

Resource Template

rosetta://{path*}

Reads bundled instruction content by resource path.

path must be a relative resource path without . or .. path segments. Blank paths are not valid resource URIs.

rosetta://rules/bootstrap-core-policy.md

Development

Local Installation

Install directly from PyPI:

pip install rosetta-mcp

Or for the latest development version, install from source if you have the code locally:

pip install -e .

Running Tests

pip install -e ".[dev]"
pytest

Building for Distribution

python -m build

Docker Image Build

The project includes a GitHub Actions workflow for automated Docker image building and publishing to GCP Artifact Registry.

Version Management: The workflow automatically extracts the version from pyproject.toml during the build process—no manual files or commits needed.

Image Tag Format: {version}-{git-short-sha} (e.g., 2.0.0b59-a1b2c3d)

Image Location: https://hub.docker.com/repository/docker/griddynamics/rosetta-mcp/general

How it works:

1. Extracts version from pyproject.toml
2. Passes version to the reusable build workflow via app-version parameter
3. Builds and tags Docker image as {version}-{git-sha}

Usage Analytics

Rosetta MCP includes built-in usage analytics via PostHog to help understand feature adoption and usage patterns.

Default Behavior

Analytics are disabled by default. No data is collected unless you deploy a PostHog instance and provide its API key.

Enable Analytics

To enable usage analytics, set POSTHOG_API_KEY and POSTHOG_HOST pointing to your PostHog instance:

{
  "mcpServers": {
    "Rosetta": {
      "env": {
        "POSTHOG_API_KEY": "phc_YOUR_PROJECT_API_KEY",
        "POSTHOG_HOST": "https://posthog.internal.company.com"
      }
    }
  }
}

Where to Find Your Project API Key:

1. Log into your PostHog dashboard
2. Navigate to: Project Settings → Project API Key
3. Copy the key (starts with phc_)

Important: Use Project API Key (write-only, for event ingestion), not Personal API Key.

What's Tracked

When enabled, Rosetta records basic operational metadata that matches information already flowing through the MCP server — no additional data is surfaced.

Per tool call:

• IP address (from the HTTP request)
• User email (from OAuth in HTTP mode) or local username (from OS environment in STDIO mode)
• Coding agent name and version (e.g. Claude Code 1.0.17)
• MCP tool called (e.g. query_instructions) and tool parameters
• MCP server version, session ID, call duration, success/error status

Excluded (stripped by before_send hook):

• limit, offset, page — pagination
• compact_view — view settings
• model, temperature, max_tokens — RAG tuning parameters

Privacy & Control

• Opt-in: Analytics disabled by default, enable by setting POSTHOG_API_KEY
• Self-hosted: You deploy and control the PostHog instance on your infrastructure
• Write-only: Project API key can only send events, cannot read analytics data
• Non-blocking: Analytics never delays or breaks MCP tool responses

Requirements

• Python >= 3.10
• Rosetta Server running and accessible
• ragflow-sdk >= 0.24.0
• mcp >= 1.26.0
• posthog >= 7.0.0 (for built-in analytics)

License

Apache-2.0 - see LICENSE file for details.

This package is built on RAGFlow by InfiniFlow, which is licensed under the Apache-2.0 License. We gratefully acknowledge the RAGFlow project and its contributors.

Links

• RAGFlow: https://github.com/infiniflow/ragflow
• Model Context Protocol: https://modelcontextprotocol.io/
• FastMCP: https://github.com/jlowin/fastmcp

Support

For issues and questions, visit the package page: https://pypi.org/project/rosetta-mcp/