Developer Guide

Who is this for? Active contributors and maintainers.

When should I read this? After Contributing. Before making your first change.

Overall Development Flow

Prepare repository.
- Fork repository entirely and work in the main branch
- Clone and create feature branch from the main branch
- Rosetta uses main as target branch for PR
- See Contributing Workflow for git-related info
Develop using claude code / codex / cursor or Use the prompting flow.
- Development: existing rules will kick in, we use HTTP MCP.
- Prompting: use the coding-agents-prompting-flow to author, refactor, or harden prompts.
Check your output.
Test locally on a target repo.
- Set up Local Instructions Mode on target repository.
- Test your prompts against a real codebase.
Test on DEV environment.
- Uninstall local-files-mode.md from target repository
- Publish to dev
- Enable Rosetta MCP or follow Quick Start to install it
- Use dev server URL https://rosetta-dev.evergreen.gcp.griddynamics.net/mcp
- Test end-to-end through the HTTP MCP
Open a PR.
- Follow the Pull Request Checklist
- Prompting: include a prompt brief, before/after examples, and validation evidence
- Coding: include tests and validation changes
- All: update documentation, including web site
Pipelines.
- Automated pipelines will execute
- Static AI review and scenario comparison
- Both must pass

Repository Layout

rosetta/
├── instructions/         ← Prompts: skills, agents, workflows, rules, templates
│   └── r2/
│       ├── core/         ← OSS foundation
│       └── <org>/        ← Organization extensions (e.g., grid/)
├── ims-mcp-server/       ← Rosetta MCP server (PyPI: ims-mcp)
│   ├── ims_mcp/          ← Server source code
│   ├── tests/            ← Unit tests (pytest)
│   └── validation/       ← verify_mcp.py integration test
├── tools/                ← Rosetta CLI (publish, verify, cleanup)
│   ├── commands/         ← CLI command implementations
│   ├── services/         ← Shared service layer
│   └── tests/            ← CLI unit tests
├── deployment/           ← Helm charts (RAGFlow)
├── plugins/              ← IDE plugin definitions
├── docs/                 ← Deep documentation (Architecture, RAGFlow, Context)
│   └── web/              ← Jekyll website (GitHub Pages)
└── refsrc/               ← Reference sources (read-only, resolves AI stale knowledge)

Prerequisites

Python 3.12+
uvx (included with uv)
Podman or Docker (optional, for Redis, used by full MCP plan_manager tests)

Local Development: Instructions

Use this when editing prompts (skills, agents, workflows, rules, templates).

Instructions run locally without MCP.

Copy them into a target repository and point your IDE using the local-files-mode.md bootstrap file.

Follow Offline Installation, except you copy your new instructions files:

  cp -r instructions/ /path/to/target-repo/instructions/

No server, no API key, no network. Edit instructions, reload, test.

Local Development: MCP

Use this when changing MCP server code, tool prompts, or bundler logic.

Run MCP locally in STDIO mode against the dev RAGFlow instance.

Redis (optional, for plan_manager)

Start a Redis-compatible container:

# Podman
podman run -d --name rosetta-redis -p 6379:6379 docker.io/valkey/valkey:latest

# Docker
docker run -d --name rosetta-redis -p 6379:6379 valkey/valkey:latest

Connect your IDE to local MCP

Claude Code:

claude mcp add --transport stdio Rosetta \
  --env ROSETTA_SERVER_URL=https://ims-dev.evergreen.gcp.griddynamics.net/ \
  --env ROSETTA_API_KEY=ragflow-xxxxx \
  --env VERSION=r2 \
  --env REDIS_URL=redis://localhost:6379/0 \
  -- uvx --prerelease=allow ims-mcp@latest

Codex:

codex mcp add Rosetta \
  --env ROSETTA_SERVER_URL=https://ims-dev.evergreen.gcp.griddynamics.net/ \
  --env ROSETTA_API_KEY=ragflow-xxxxx \
  --env VERSION=r2 \
  --env REDIS_URL=redis://localhost:6379/0 \
  -- uvx --prerelease=allow ims-mcp@latest

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "Rosetta": {
      "command": "uvx",
      "args": ["--prerelease=allow", "ims-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "https://ims-dev.evergreen.gcp.griddynamics.net/",
        "ROSETTA_API_KEY": "ragflow-xxxxx",
        "VERSION": "r2",
        "REDIS_URL": "redis://localhost:6379/0"
      }
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "Rosetta": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--prerelease=allow", "ims-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "https://ims-dev.evergreen.gcp.griddynamics.net/",
        "ROSETTA_API_KEY": "ragflow-xxxxx",
        "VERSION": "r2",
        "REDIS_URL": "redis://localhost:6379/0"
      }
    }
  }
}

API key: Get yours from the RAGFlow UI. The dataset you test against must be owned by user of this API key.

VERSION: Set explicitly here for local development testing. Always test with both VERSION=r1 and VERSION=r2.

Pre-release builds: Version suffixes like b00 trigger automatic pre-release publishing. Use --prerelease=allow with uvx to pull these builds.

Add the bootstrap rule to your IDE as defined in Quick Start — Add Bootstrap Rule.

Local Development: CLI

Use this when changing publish, verify, or cleanup commands.

cd tools
bash setup.sh           # One-time: creates venv, installs deps
source venv/bin/activate
cp .env.dev .env        # Points at dev RAGFlow instance
python ims_cli.py verify

Preview changes without publishing:

python ims_cli.py publish ../instructions --dry-run

The --dry-run flag shows what would be published (new, changed, unchanged files) without writing anything to RAGFlow.

Validation

MCP integration tests

# From repo root, with tools/venv activated
VERSION=r1 python ims-mcp-server/validation/verify_mcp.py
VERSION=r2 python ims-mcp-server/validation/verify_mcp.py

# With Redis (tests plan_manager with RedisPlanStore)
REDIS_URL="redis://localhost:6379/0" VERSION=r2 python ims-mcp-server/validation/verify_mcp.py

Run both r1 and r2. If your change touches Redis-dependent features, run with and without REDIS_URL.

Unit tests

# MCP server tests
tools/venv/bin/pytest ims-mcp-server/tests

# CLI tests
cd tools && PYTHONPATH=. venv/bin/pytest tests

Type checking

./validate-types.sh

Run this after any Python code change.

Dev Environment: Integration Testing

After local validation passes, test end-to-end against the dev environment.

Environments (two separate servers):

Rosetta Server (RAGFlow) prod: https://ims.evergreen.gcp.griddynamics.net/ — document engine backend, dataset management, API keys
Rosetta Server (RAGFlow) dev: https://ims-dev.evergreen.gcp.griddynamics.net/ — used by STDIO MCP and CLI for publishing
Rosetta HTTP MCP prod: https://rosetta.evergreen.gcp.griddynamics.net/mcp — production MCP endpoint for end users
Rosetta HTTP MCP dev: https://rosetta-dev.evergreen.gcp.griddynamics.net/mcp — dev MCP endpoint for integration testing

1. Publish instructions to dev

cd tools
source venv/bin/activate
cp .env.dev .env
python ims_cli.py publish ../instructions

This publishes to the dev RAGFlow instance. Only changed files are uploaded (MD5-based change detection). Use --force to republish everything.

2. Test MCP (STDIO against dev)

Connect your IDE using the STDIO configs from Local Development: MCP. This validates that your published instructions are served correctly through the MCP layer.

3. Test Instructions from MCP (HTTP, default mode)

This is the mode end users run. Connect your IDE to the hosted dev MCP endpoint over HTTP.