SIM-ONE

SIM-ONE mcp_server Migration Plan

Status: Planning Phase Created: January 2025 Target Timeline: 6-12 months Priority: Medium (No immediate action required)

Executive Summary

The mcp_server directory name predates the now-standard “Model Context Protocol” (MCP) term in the AI industry. To prevent confusion and improve discoverability, this document outlines a gradual migration strategy to rename the directory to agent_core while maintaining complete backward compatibility and preserving all existing links, documentation, and integrations.

Background

Current Situation

The SIM-ONE Framework uses mcp_server to refer to:

Industry Confusion

The term “MCP” now commonly refers to:

Why This Matters

Migration Strategy

Phase 1: Documentation & Clarification (CURRENT - Months 1-2)

Status: ✅ In Progress (Phase 22)

Actions:

Goal: Ensure all users understand current naming context

Phase 2: Preparation & Planning (Months 3-4)

Actions:

Deliverables:

Phase 3: Infrastructure Preparation (Months 5-6)

Actions:

Deliverables:

Compatibility Layer Example:

# code/agent_core/__init__.py
"""
SIM-ONE Agent Core (formerly mcp_server)
Provides backward compatibility imports for mcp_server namespace
"""
import warnings
from pathlib import Path

# Re-export everything from agent_core as if it were mcp_server
from .protocols import *
from .orchestration_engine import *
from .cognitive_governance_engine import *

def _emit_deprecation_warning():
    """Optionally warn about legacy mcp_server imports"""
    if os.getenv("SIMONE_WARN_LEGACY_IMPORTS", "false").lower() == "true":
        warnings.warn(
            "Importing from 'mcp_server' is deprecated. "
            "Please update imports to 'agent_core'. "
            "See MIGRATION_PLAN.md for details.",
            DeprecationWarning,
            stacklevel=3
        )

Phase 4: Gradual Code Migration (Months 7-9)

Actions:

Migration Priority:

  1. New code: All new modules use agent_core
  2. Core systems: Orchestrator, governance engine
  3. Protocols: Individual protocol modules
  4. Utilities: Supporting modules and tools
  5. Tests: Test suite references
  6. Documentation: Internal docs and comments

Principle: No breaking changes - both imports work simultaneously

Phase 5: External Communication (Months 10-11)

Actions:

Deliverables:

Phase 6: Legacy Support & Monitoring (Month 12+)

Actions:

Long-term Strategy:

Directory Renaming Options

Pros:

Cons:

Verdict: ✅ Recommended

Option 2: cognitive_orchestrator

Pros:

Cons:

Verdict: ⚠️ Alternative option

Option 3: simone_core

Pros:

Cons:

Verdict: ⚠️ Fallback option

Decision: Proceed with agent_core unless stakeholder feedback suggests otherwise.

URL & Link Preservation Strategy

Documentation URLs

Current:

Strategy:

  1. GitHub: Directory rename automatically preserves most GitHub links (redirects)
  2. Documentation: Use relative links where possible (e.g., ../agent_core/)
  3. Hardcoded URLs: Create redirect/compatibility layer
  4. External links: Cannot control, but GitHub handles redirects

Action Items:

Import Compatibility Strategy

Current Import Pattern

from mcp_server.protocols.rep import REP
from mcp_server.orchestration_engine import OrchestrationEngine

Future Import Pattern (Preferred)

from agent_core.protocols.rep import REP
from agent_core.orchestration_engine import OrchestrationEngine

Compatibility Layer Implementation

Approach: Create import aliasing at package level

# code/mcp_server/__init__.py (becomes compatibility shim)
"""
LEGACY COMPATIBILITY LAYER
This module provides backward compatibility for code importing from 'mcp_server'.
New code should import from 'agent_core' instead.
See MIGRATION_PLAN.md for migration guide.
"""
import warnings
import os

# Re-export everything from agent_core
from agent_core import *
from agent_core.protocols import *
from agent_core.orchestration_engine import *
from agent_core.cognitive_governance_engine import *

# Optional deprecation warning
if os.getenv("SIMONE_WARN_LEGACY_IMPORTS", "false").lower() == "true":
    warnings.warn(
        "Importing from 'mcp_server' is deprecated. Update imports to 'agent_core'.",
        DeprecationWarning,
        stacklevel=2
    )

Result: Both import paths work identically, allowing gradual migration.

SEO/AEO Preservation

Current SEO Investment

The mcp_server directory has accumulated:

Preservation Strategy

  1. GitHub Redirects: Leverage GitHub’s automatic redirects for renamed files/directories
  2. Documentation Updates: Update all controlled documentation gradually
  3. Redirect Notes: Add “formerly mcp_server” references in meta descriptions
  4. Gradual Rollout: Allows search engines to re-index gradually
  5. Canonical URLs: Use canonical link tags to point to new paths

Action Items:

Testing & Validation

Pre-Migration Tests

During-Migration Tests

Post-Migration Tests

Rollback Plan

If migration encounters critical issues:

Rollback Triggers

Rollback Process

  1. Pause migration announcements
  2. Revert documentation to prefer mcp_server terminology
  3. Disable deprecation warnings
  4. Investigate root cause
  5. Revise migration plan
  6. Re-communicate updated timeline

Note: Due to compatibility layer, rollback is low-risk and can happen at any time.

Communication Timeline

Internal Communication

External Communication

Success Criteria

Migration is considered successful when:

Open Questions

Stakeholder Sign-Off

This migration plan requires approval from:

Timeline Overview

Phase Months Status Key Deliverable
Phase 1: Documentation 1-2 ✅ In Progress Naming clarifications added
Phase 2: Planning 3-4 ⏳ Pending Reference audit complete
Phase 3: Infrastructure 5-6 ⏳ Pending Compatibility layer working
Phase 4: Code Migration 7-9 ⏳ Pending Internal code migrated
Phase 5: External Comms 10-11 ⏳ Pending Public announcement made
Phase 6: Long-term Support 12+ ⏳ Pending Compatibility maintained

Total Timeline: 12+ months Current Phase: Phase 1 (Documentation & Clarification)

References

Change Log

Date Version Changes Author
2025-01-10 1.0 Initial migration plan created SIM-ONE Team

This is a living document and will be updated as the migration progresses.

This site is open source. Improve this page.