MCP Context Share

MCP上下文共享基准测试（MS MARCO）

一个完整的， 工作 用于再现情境共享策略实证评估的基准和分析套件 （广播、发布-订阅、按需拉取、分层缓存、混合自适应） 马科女士的文章 数据集。

🎯 研究目标

使用MS MARCO数据集中的实际工作负载，系统地评估跨性能、开销和一致性指标的五种上下文共享策略，为多代理系统设计提供循证指导。

策略

• 广播（不列颠哥伦比亚省） –将每次写入推送到所有代理（强一致性、高网络）
• 发布-订阅（PS） –主题频道；向订阅者推送（最终一致性）
• 按需拉动（PD） –读取失败时获取（一致性差，网络低）
• 分层缓存（HC） –L1（代理）、L2（组）、L3（全局）缓存（最终）
• 混合自适应（HA） –根据工作负载/规模在运行时选择策略

🚀 快速开始

# Clone repository
git clone https://github.com/ogsmin123/MCPContextShare.git
cd mcp-context-sharing-msmarco

需求

• Python 3.11+
• 操作系统：Linux/macOS（在Ubuntu 24.04上测试）

步骤1：环境设置

# Create virtual environment
python -m venv venv

# Activate environment
# On Linux/Mac:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

步骤2：安装依赖项

# Install core dependencies
pip install -r requirements.txt

# Install development dependencies (optional)
pip install -r requirements-dev.txt

步骤3：系统配置

(可选步骤，仅在计划创建自己的Curated配置目录时才需要 配置)

python scripts/generate_configs.py --out configs/generated --seed 42

步骤4：数据集（MS MARCO段落）和整理结果（758种配置）

MS MARCO已获得微软研究院的研究使用许可。您必须在MS MARCO网站上接受许可证。 将以下内容放在下面 .data/msmarco/:

• collection.tsv
• queries.dev.tsv
• qrels.dev.tsv

数据集可以从官方网站下载 马可女士:https://microsoft.github.io/msmarco/ 或者来自作者的kaggle公共数据集位置：https://www.kaggle.com/datasets/ogsmin/mcpcontextshare-data

下载后，将数据目录放入项目目录中。 您不需要使用这些数据，因为我们已经从这些数据集中创建了经过策划的758个配置，并存储在结果文件夹中。 结果文件夹可以从作者的Kaggle公共数据集位置下载：https://www.kaggle.com/datasets/ogsmin/mcpcontextshare-results

下载后，将结果目录放入项目目录中。结果

results/
├── agg                 # Curated per-second aggregates (CSV) from MS Marco dataset                 
│   ├── C001.csv
│   ├── C001.manifest.json
........
├── raw/                # per-operation logs (Parquet) from MS Marco dataset
│   └── C001.parquet    
........
├── figures/            # generated figures (PNG/SVG)

第五步：进行实验

(可选步骤，仅在计划创建自己的Curated结果目录时才需要 结果)

# single config
python scripts/run_all_experiments.py --config configs/default.yaml
# batch
python scripts/run_all_experiments.py --glob "configs/generated/*.yaml"

每次运行包括：5秒初始化，30秒预热（未测量），300秒测量，10秒冷却。

输出：

• 每次操作日志→ results/raw/*.parquet
• 每秒骨料→ results/agg/*.csv
• 清单→ results/agg/.manifest.json

步骤6：生成可视化

python analysis/aggregate_results.py
python analysis/statistical_tests.py
python analysis/visualization.py

生成：

• tables/summary.csv
• 数字在 results/figures/ （延迟直方图；根据需要扩展）

目录结构

mcp-context-sharing-msmarco/
├─ README.md
├─ requirements.txt           # Dependencies
├─ requirements-py312.txt     # Dependencies for Python 3.12
├─ setup.sh                   # Env Setup
├─ configs/                   # Configurations
│ └─ default.yaml
│ └─ generated          
│    └─ C001.yaml
.......
├─ scripts/                  # Scripts for generating configs and running experiment
│ ├─ generate_configs.py
│ └─ run_all_experiments.py
├─ mcpbench/                 # Primary code base directory
│ ├─ __init__.py
│ ├─ config.py
│ ├─ utils.py
│ ├─ context_store.py
│ ├─ message_router.py
│ ├─ agent.py
│ ├─ workload.py
│ ├─ metrics.py
│ └─ strategies/            # Different Strategy code base directory
│    ├─ base.py
│    ├─ broadcast.py
│    ├─ pubsub.py
│    ├─ pull_on_demand.py
│    ├─ hierarchical_cache.py
│    └─ hybrid_adaptive.py
├─ analysis/               # Scripts for generating visualization.
│ ├─ aggregate_results.py
│ ├─ statistical_tests.py
│ └─ visualization.py