ims-mcp 2.0.0b58

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

• 🔍 Semantic Search - Vector-based and full-text search across documents
• 🤖 RAG Queries - Retrieval-augmented generation with configurable LLM settings
• 📝 Document Management - Upload, update, list, and delete documents with upsert semantics
• 🏷️ Metadata Filtering - Advanced filtering by tags, domain, and custom metadata
• 🌐 Environment-Based Config - Zero configuration, reads from environment variables
• 📋 Bootstrap Instructions - Automatically includes PREP step instructions for LLMs on connection
• 📊 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

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",
        "VERSION": "r2",
        "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" \
VERSION=r2 \
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" \
VERSION=r2 \
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. search

Perform semantic and full-text search across documents.

Parameters:

• query (str): Search query
• filters (dict, optional): Metadata filters (e.g., {"tags": {"$in": ["agents"]}})
• limit (int, optional): Maximum results
• use_semantic_search (bool, optional): Enable vector search
• use_fulltext_search (bool, optional): Enable full-text search

Example:

search("machine learning", filters={"tags": {"$in": ["research"]}}, limit=5)

2. rag

Retrieval-augmented generation with LLM.

Parameters:

• query (str): Question to answer
• filters (dict, optional): Metadata filters
• limit (int, optional): Max search results to use
• model (str, optional): LLM model name
• temperature (float, optional): Response randomness (0-1)
• max_tokens (int, optional): Max response length

Example:

rag("What is machine learning?", model="gpt-4", temperature=0.7)

3. put_document

Upload or update a document with upsert semantics.

Parameters:

• content (str): Document text content
• title (str): Document title
• metadata (dict, optional): Custom metadata (e.g., {"tags": ["research"], "author": "John"})
• document_id (str, optional): Explicit document ID

Example:

put_document(
    content="Machine learning is...",
    title="ML Guide",
    metadata={"tags": ["research", "ml"]}
)

4. list_documents

List documents with pagination and optional tag filtering.

Parameters:

• offset (int, optional): Documents to skip (default: 0)
• limit (int, optional): Max documents (default: 100)
• document_ids (list[str], optional): Specific IDs to retrieve
• compact_view (bool, optional): Show only ID and title (default: True)
• tags (list[str], optional): Filter by tags (e.g., ["agents", "r1"])
• match_all_tags (bool, optional): If True, document must have ALL tags; if False (default), document must have ANY tag

Examples:

# List all documents (compact view - ID and title only)
list_documents(offset=0, limit=10)

# List with full details
list_documents(offset=0, limit=10, compact_view=False)

# Filter by tags (ANY mode - documents with "research" OR "ml")
list_documents(tags=["research", "ml"])

# Filter by tags (ALL mode - documents with both "research" AND "ml")
list_documents(tags=["research", "ml"], match_all_tags=True)

Note: Tag filtering is performed client-side after fetching results. For large collections with complex filtering needs, consider using the search() tool with metadata filters instead.

5. get_document

Retrieve a specific document by ID or title.

Parameters:

• document_id (str, optional): Document ID
• title (str, optional): Document title

Example:

get_document(title="ML Guide")

6. delete_document

Delete a document by ID.

Parameters:

• document_id (str, required): The unique identifier of the document to delete

Example:

delete_document(document_id="550e8400-e29b-41d4-a716-446655440000")

Returns:

• Success message with document ID on successful deletion
• Error message if document not found or permission denied

Metadata Filtering

All filter operators supported:

• $eq: Equal
• $neq: Not equal
• $gt, $gte: Greater than (or equal)
• $lt, $lte: Less than (or equal)
• $in: In array
• $nin: Not in array
• $like, $ilike: Pattern matching (case-sensitive/insensitive)

Examples:

# Filter by tags
filters={"tags": {"$in": ["research", "ml"]}}

# Filter by domain
filters={"domain": {"$eq": "instructions"}}

# Combined filters
filters={"tags": {"$in": ["research"]}, "created_at": {"$gte": "2024-01-01"}}

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",
        "VERSION": "r2",
        "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 version (mcp_server_version: "1.0.30")
• 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):

• query - Search queries
• filters, tags - Filter/tag usage patterns
• title - Document title searches
• document_id, document_ids - Document access patterns (kept for tracking)
• use_semantic_search, use_fulltext_search - Search method preferences
• match_all_tags - Tag matching logic

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/