ims-mcp 2.0.0b64

Model Context Protocol server for Rosetta (Instruction Management System)

ims-mcp

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

Powered by R2R technology 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.

Features

• 🧭 Context Bootstrap - get_context_instructions loads bootstrap rules for agent setup
• 📚 Instruction Retrieval - query_instructions fetches docs by keyword or tags
• 🗂️ Project Context Management - discover, query, and store project datasets
• 📝 Feedback Capture - structured submit_feedback for workflow learning loops
• 🔗 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 ims-mcp is with uvx, which automatically handles installation:

uvx ims-mcp@latest

Using pip

Install globally or in a virtual environment:

pip install ims-mcp

Then run:

ims-mcp

As a Python Module

You can also run it as a module:

python -m ims_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

Variable	Scope	Default	Notes
ROSETTA_SERVER_URL	Runtime (all modes)	http://localhost:80	Rosetta Server base URL
ROSETTA_API_KEY	Runtime (all modes)	Empty	Required for Rosetta Server access
VERSION	Runtime (all modes)	r1	Used for instruction dataset resolution (aia-{version})
ROSETTA_TRANSPORT	Runtime (all modes)	stdio	stdio or http
ROSETTA_HTTP_HOST	Runtime (HTTP)	0.0.0.0	HTTP bind host
ROSETTA_HTTP_PORT	Runtime (HTTP)	8000	HTTP bind port
REDIS_URL	Runtime (HTTP)	Empty	Optional Redis session store; empty uses in-memory store
ROSETTA_ALLOWED_ORIGINS	Runtime (HTTP)	Empty	Comma-separated Origin allowlist
ROSETTA_OAUTH_AUTHORIZATION_ENDPOINT	Runtime (HTTP OAuth)	Empty	OAuth authorize endpoint
ROSETTA_OAUTH_TOKEN_ENDPOINT	Runtime (HTTP OAuth)	Empty	OAuth token endpoint
ROSETTA_OAUTH_INTROSPECTION_ENDPOINT	Runtime (HTTP OAuth)	Empty	Token introspection endpoint
ROSETTA_OAUTH_CLIENT_ID	Runtime (HTTP OAuth)	Empty	OAuth client ID
ROSETTA_OAUTH_CLIENT_SECRET	Runtime (HTTP OAuth)	Empty	OAuth client secret
ROSETTA_OAUTH_BASE_URL	Runtime (HTTP OAuth)	Empty	Public MCP URL used for callback generation; fallback is http://{ROSETTA_HTTP_HOST}:{ROSETTA_HTTP_PORT}
ROSETTA_OAUTH_CALLBACK_PATH	Runtime (HTTP OAuth)	/auth/callback	OAuth callback path mounted by Rosetta MCP
ROSETTA_READ_POLICY	Runtime (authz)	all	all, team, none for project dataset reads
ROSETTA_WRITE_POLICY	Runtime (authz)	all	all, team, none for project dataset writes/creates
ROSETTA_USER_EMAIL	Runtime (authz)	[e-mail]	STDIO identity and HTTP fallback identity
ROSETTA_INVITE_EMAILS	Runtime (authz)	Empty	Comma-separated invite list for project dataset creation flow
ROSETTA_MODE	Runtime (prompts)	HARD	Prompt mode selection: HARD or SOFT
INSTRUCTION_ROOT_FILTER	Runtime (instructions query)	Empty	Comma-separated root tags filter
IMS_DEBUG	Runtime (debug)	Disabled	Enable debug logs (1, true, yes, on)
POSTHOG_API_KEY	Runtime (analytics)	Package-injected key	Set to "" to disable analytics
POSTHOG_HOST	Runtime (analytics)	https://us.i.posthog.com	PostHog endpoint
USER	Runtime (analytics context)	OS-dependent	Username source (priority 1)
USERNAME	Runtime (analytics context)	OS-dependent	Username source (priority 2)
LOGNAME	Runtime (analytics context)	OS-dependent	Username source (priority 3)

Shared Variables (Both Modes)

Variable	Description	Default
ROSETTA_SERVER_URL	Rosetta Server base URL	http://localhost:80
ROSETTA_API_KEY	API key used by Rosetta MCP to access Rosetta Server	Required
VERSION	Instruction release used for instruction dataset resolution (aia-{version})	r1
IMS_DEBUG	Enable debug logging to stderr (1/true/yes/on)	Disabled
POSTHOG_API_KEY	PostHog project API key (set "" to disable analytics)	Package default
POSTHOG_HOST	PostHog host	https://us.i.posthog.com

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=[e-mail]

HTTP Mode

Set:

ROSETTA_TRANSPORT=http
ROSETTA_HTTP_HOST=0.0.0.0
ROSETTA_HTTP_PORT=8000

Optional HTTP runtime settings:

Variable	Description	Default
REDIS_URL	Shared session store for multi-instance deployments	In-memory store
ROSETTA_ALLOWED_ORIGINS	Comma-separated allowlist for Origin header validation	No restriction

OAuth variables for HTTP mode:

Variable	Description
ROSETTA_OAUTH_AUTHORIZATION_ENDPOINT	Keycloak authorize URL
ROSETTA_OAUTH_TOKEN_ENDPOINT	Keycloak token URL
ROSETTA_OAUTH_INTROSPECTION_ENDPOINT	Keycloak introspection URL
ROSETTA_OAUTH_CLIENT_ID	OAuth client ID
ROSETTA_OAUTH_CLIENT_SECRET	OAuth client secret
ROSETTA_OAUTH_BASE_URL	Public Rosetta MCP base URL used to build OAuth callback URLs
ROSETTA_OAUTH_CALLBACK_PATH	OAuth callback path (default /auth/callback)

Authorization policy variables (dataset-level):

Variable	Description	Default
ROSETTA_READ_POLICY	all, team, none for read access on project-* datasets	all
ROSETTA_WRITE_POLICY	all, team, none for write/create on project-* datasets	all
ROSETTA_USER_EMAIL	Fallback user email (used in STDIO, and HTTP fallback)	[e-mail]
ROSETTA_INVITE_EMAILS	Comma-separated emails auto-invited on project dataset creation	Empty

OAuth callback URL examples:

• Production: https://rosetta.evergreen.gcp.griddynamics.net/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": ["ims-mcp@latest"],
      "env": {
        "ROSETTA_TRANSPORT": "stdio",
        "ROSETTA_SERVER_URL": "https://ims.evergreen.gcp.griddynamics.net",
        "ROSETTA_API_KEY": "your-rosetta-api-key",
        "ROSETTA_USER_EMAIL": "[e-mail]"
      }
    }
  }
}

HTTP Mode (Server deployment)

Start Rosetta MCP in HTTP mode:

ROSETTA_TRANSPORT=http \
ROSETTA_SERVER_URL="https://ims.evergreen.gcp.griddynamics.net" \
ROSETTA_API_KEY="your-rosetta-api-key" \
ROSETTA_HTTP_HOST=0.0.0.0 \
ROSETTA_HTTP_PORT=8000 \
ROSETTA_OAUTH_AUTHORIZATION_ENDPOINT="https://keycloak.evergreen.gcp.griddynamics.net/realms/<realm>/protocol/openid-connect/auth" \
ROSETTA_OAUTH_TOKEN_ENDPOINT="https://keycloak.evergreen.gcp.griddynamics.net/realms/<realm>/protocol/openid-connect/token" \
ROSETTA_OAUTH_INTROSPECTION_ENDPOINT="https://keycloak.evergreen.gcp.griddynamics.net/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.evergreen.gcp.griddynamics.net" \
ims-mcp

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

ROSETTA_TRANSPORT=http \
ROSETTA_SERVER_URL="https://ims.evergreen.gcp.griddynamics.net" \
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://keycloak.evergreen.gcp.griddynamics.net/realms/<realm>/protocol/openid-connect/auth" \
ROSETTA_OAUTH_TOKEN_ENDPOINT="https://keycloak.evergreen.gcp.griddynamics.net/realms/<realm>/protocol/openid-connect/token" \
ROSETTA_OAUTH_INTROSPECTION_ENDPOINT="https://keycloak.evergreen.gcp.griddynamics.net/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.evergreen.gcp.griddynamics.net" \
ims-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": "https://rosetta.evergreen.gcp.griddynamics.net/mcp"
    }
  }
}

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.

Example:

query_instructions(tags=["bootstrap"])

3. submit_feedback

Store workflow feedback for continuous improvement.

Parameters:

• request_mode (str): Workflow mode, e.g. coding.md
• feedback (dict): Structured payload with required keys:
  • summary
  • root_cause
  • prompt_suggestions
  • context

Example:

submit_feedback(
    request_mode="coding.md",
    feedback={
        "summary": "User asked for README fixes.",
        "root_cause": "README had stale tool docs.",
        "prompt_suggestions": "Keep README in sync with tool surface.",
        "context": "ims-mcp-server README alignment"
    }
)

4. discover_projects

List project datasets (project-*) available in Rosetta Server.

Parameters:

• query (str, optional): Name filter

Example:

discover_projects(query="rulesofpower")

5. query_project_context

Query documents inside a project dataset.

Parameters:

• repository_name (str): Project name (prefix project- is handled internally)
• query (str, optional): Keyword query
• tags (list[str], optional): Tag filter
• topic (str, optional): Tracking-only intent hint

Example:

query_project_context(
    repository_name="rulesofpower",
    tags=["architecture"]
)

6. store_project_context

Create or update a project context document.

Parameters:

• repository_name (str): Project name
• document (str): Document name
• tags (list[str]): Document tags
• content (str): Document body
• force (bool, optional): If true, creates dataset when missing

Example:

store_project_context(
    repository_name="rulesofpower",
    document="ARCHITECTURE.md",
    tags=["architecture", "backend"],
    content="# Architecture\\n...",
    force=True
)

Resource Template

rosetta://{path*}

Reads bundled instruction content by resource path.

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

Development

Local Installation

Install directly from PyPI:

pip install ims-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

Usage Analytics

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

Default Behavior

Published packages (from PyPI via CI/CD): Analytics are ENABLED BY DEFAULT with a built-in Project API Key (write-only, safe for client-side use). No configuration required.

Local development builds: Analytics are DISABLED (placeholder key remains in source code).

Disable Analytics

To disable analytics, set POSTHOG_API_KEY to an empty string in your MCP configuration:

{
  "mcpServers": {
    "KnowledgeBase": {
      "command": "uvx",
      "args": ["ims-mcp@latest"],
      "env": {
        "ROSETTA_TRANSPORT": "stdio",
        "ROSETTA_SERVER_URL": "https://ims.evergreen.gcp.griddynamics.net",
        "ROSETTA_API_KEY": "your-rosetta-api-key",
        "POSTHOG_API_KEY": ""
      }
    }
  }
}

Use Custom PostHog Project

To track analytics in your own PostHog project, provide your Project API Key:

{
  "mcpServers": {
    "KnowledgeBase": {
      "env": {
        "POSTHOG_API_KEY": "phc_YOUR_CUSTOM_PROJECT_API_KEY",
        "POSTHOG_HOST": "https://us.i.posthog.com"
      }
    }
  }
}

Where to Find Your Project API Key:

1. Log into 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

User Context:

• Username (from USER/USERNAME/LOGNAME environment variables + whoami fallback)
• Repository names (from MCP roots/list protocol request, comma-separated if multiple; fallback to client_id parsing; 5-min cache)
• MCP server identifier (mcp_server: "Rosetta") and runtime package version (mcp_server_version)
• GeoIP enabled via disable_geoip=False in client initialization (MCP runs locally on user's machine, IP is user's actual location)

Business Parameters (usage patterns):

• Tool arguments such as query, tags, repository_name, request_mode, document, and force

Excluded (technical parameters):

• limit, offset, page - Pagination
• compact_view - View settings
• model, temperature, max_tokens - RAG tuning parameters

Privacy & Control

• Opt-out: Analytics enabled by default with built-in key, easy to disable
• Write-only: Project API key can only send events, cannot read analytics data
• Non-blocking: Analytics never delays or breaks MCP tool responses
• User control: Set POSTHOG_API_KEY="" to disable tracking anytime
• Custom tracking: Use your own PostHog project by setting custom API key

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

MIT License - see LICENSE file for details

This package is built on R2R (RAG to Riches) technology by SciPhi AI, which is licensed under the MIT License. We gratefully acknowledge the R2R project and its contributors.

Links

• R2R Technology: https://github.com/SciPhi-AI/R2R
• 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/ims-mcp/