IMS MCP服务器

MCP服务器，通过模型上下文协议Python SDK.

它封装了现有的IMS HTTP后端（会话内存、内存核、网络接口等），上下文rag），并使这些功能可供MCP感知的客户端使用（例如mcphub、Warp、VS Code、LibreChat）。

先决条件

Python 3.10+
运行在可访问位置的IMS后端（FastAPI/Uvicorn服务），例如：

- http://localhost:8000，或 - http://ims.delongpa.com

就是这样！MCP服务器包括通信所需的所有客户端代码 IMS后端。

安装（真空+管道）

从 ims-mcp 目录：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

这将安装MCP Python SDK和所需的依赖项（httpx）。

配置

MCP服务器通过环境变量与IMS通信。这些可以提供以三种方式（按顺序增加优先级）：

本地人 .env 项目根目录中的文件（或由指定的路径）

IMS_ENV_FILE)

流程环境（例如shell中的导出变量）
MCP主机设置的环境变量（例如mcphub env 块）

支持的变量：

IMS_BASE_URL （可选，默认 https://ims.delongpa.com)

- IMS HTTP服务的基本URL（覆盖本地开发，例如。 http://localhost:8000).

IMS_HTTP_TIMEOUT （可选，默认 5.0 秒）
IMS_CLIENT_NAME （可选，默认 "ims-mcp")
IMS_VERIFY_SSL （可选，默认 true)

- 设置为 false 仅适用于具有自签名证书的本地/dev环境。

IMS_ENV_FILE （可选，默认 .env)

- 如果设置，则指向 .env-在读取其他变量之前加载样式文件。

IMS_HEALTH_PROJECT_ID （可选，默认 ims-mcp)

- 由使用的项目id ims://health 探测读取端点时的资源。

使用.env文件（本地开发）

创建一个名为的文件 .env 旁边 server.py （仅当您想覆盖默认值时才需要，例如本地开发）：

IMS_BASE_URL=http://localhost:8000
IMS_HTTP_TIMEOUT=5.0
IMS_CLIENT_NAME=ims-mcp

您可以用以下命令覆盖文件名/路径 IMS_ENV_FILE 如果需要的话。

直接设置变量

使用导出变量的示例：

export IMS_BASE_URL="http://ims.delongpa.com"
export IMS_HTTP_TIMEOUT="5.0"
export IMS_CLIENT_NAME="ims-mcp"
export IMS_VERIFY_SSL="true"

在本地运行MCP服务器

启动静脉（可选 IMS_BASE_URL 设置）：

source .venv/bin/activate
# Optional override for local dev:
# export IMS_BASE_URL="http://localhost:8000"
python server.py

服务器在stdio上运行，这是MCP客户端在生成时所期望的它作为一个子流程。

mcphub配置示例

在克隆此仓库的主机上从mcphub使用此服务器 /opt/mcps/ims-mcp 并如上所述创建了venv，添加一个条目，如下所示：

"IMS-MCP": {
  "type": "stdio",
  "command": "/opt/mcps/ims-mcp/.venv/bin/python",
  "args": [
    "/opt/mcps/ims-mcp/server.py"
  ],
  "env": {
    "IMS_BASE_URL": "http://ims.delongpa.com"
  }
}

调整路径和 IMS_BASE_URL 以适应您的环境。

外露工具

MCP服务器公开了以下与IMS功能交互的工具：

上下文检索

ims.context-rag.context_search

- 通过可选的图形扩展跨代码、文档和内存进行统一搜索 - 第四阶段新增： expand_graph （默认值：true）和 graph_depth （默认值：2）参数 - 当 expand_graph=true，矢量搜索结果通过本体图中的相关实体进行丰富

文档索引（Meilisearch）

docs_index_directory

- 为目录建立索引 *文本* 将文件（docs+code+config）导入Meilisearch project_docs （默认情况下分块） - 用途 IMS_MEILI_URL / IMS_MEILI_API_KEY 和商店 user_id （从 IMS_USER_ID 或操作系统用户名） - 支持可选的基于路径的过滤： - include_globs：仅包含与至少一个glob匹配的文件（例如。 **/*-meta.xml Salesforce元数据） - exclude_globs：排除与任何glob匹配的文件 - no_default_excludes：禁用内置排除（例如。 .env*，锁文件， *.min.js)

长时程记忆

ims.memory-core.store_memory

- 存储决策、问题和事实 - 第四阶段新增： 自动创建本体图节点 - kind="decision" → 在Neo4j中创建决策节点 - kind="issue" → 在Neo4j中创建Bug节点 - kind="fact"/"note" → 仅内存（无图形节点） - 支持对决策和错误的关系跟踪和影响分析

ims.memory-core.find_memories

- 搜索存储的记忆

会话状态

ims.session-memory.auto_session

- 用于恢复或创建会话的智能助手

ims.session-memory.resolve_session

- 钩子感知解析器，恢复/创建会话并绑定 hook_session_id 将会话元数据转换为严格的会话门控

ims.session-memory.get_bound_session

- 查找助手以验证是否 hook_session_id 已绑定到项目的开放IMS会话

ims.session-memory.continue_session

- 通过（项目、用户、代理、任务）元组解析或创建会话

ims.session-memory.checkpoint_session

- 在突发期间保持会话状态（保存进度而不暗示暂停/切换）

ims.session-memory.wrap_session

- 将更新的会话状态保持在真实边界（暂停/切换/结束）

ims.session-memory.list_open_sessions

- 列出可用会话

ims.session-memory.resume_session

- 按ID恢复特定会话

跨项目交接

handoff_create

- 创建跨项目移交任务 - 编排：任务内存（GitHub Issue）、内存核心（切换说明）、会话内存（种子目标会话） - 支持项目注册表集成，以自动解析GitHub仓库

图操作（本体论）

ims.graph.create_node

- 创建本体节点（决策、Bug、特征、组件、纠正、反射、模式、课程）

ims.graph.create_relationship

- 在节点（实现、块、影响等）之间创建关系

ims.graph.impact_analysis

- 找出受实体更改影响的内容

ims.graph.blocking_analysis

- 识别阻碍功能的错误

ims.graph.architectural_drift

- 根据被取代的决定检测组件

ims.graph.lookup_patterns

- 查找适用于组件的模式

ims.graph.corrections_ready

- 查找已准备好升级到模式的更正

ims.graph.promote_correction

- 促进对可重用模式的纠正

每个工具在其docstring中都包含全面的文档 IMS协议和使用指南，请参阅 AGENTS.md.

客户端库使用情况

这 app/ 目录为直接编程访问IMS提供了客户端库：

from app.ims_client import IMSClient

ims = IMSClient()

# Session management
session = ims.session_memory.continue_session(
    project_id="my-project",
    agent_id="implementer",
    task_id="add-feature"
)

# Long-term memory with automatic graph node creation
# kind="decision" automatically creates a Decision node in Neo4j
memory = ims.memory_core.store_memory(
    project_id="my-project",
    text="Use Redis for session state. Rationale: Need TTL and atomic ops.",
    kind="decision",  # Creates Decision node in graph
    tags=["architecture", "redis"],
    importance=0.9
)

# kind="issue" automatically creates a Bug node in Neo4j
ims.memory_core.store_memory(
    project_id="my-project",
    text="Auth timeout bug fixed by increasing session TTL to 1 hour",
    kind="issue",  # Creates Bug node in graph
    tags=["bug", "auth"]
)

# Context search with graph expansion (default)
results = ims.context_rag.context_search(
    project_id="my-project",
    query="How is authentication handled?",
    sources=["code", "docs", "memories"],
    expand_graph=True,  # Default: enrich with graph relationships
    graph_depth=2       # Default: traverse 2 levels deep
)

# Vector-only search (disable graph expansion)
results = ims.context_rag.context_search(
    project_id="my-project",
    query="authentication patterns",
    sources=["code"],
    expand_graph=False  # Disable graph expansion for pure vector search
)

# Graph operations (ontology)
node_id = ims.graph.create_node(
    node_type="Decision",
    properties={
        "text": "Use Redis for session state",
        "project_id": "my-project",
        "rationale": "Low latency, TTL support"
    }
)

# Create relationships
ims.graph.create_relationship(
    from_id=decision_node_id,
    rel_type="affects",
    to_id=component_node_id,
    properties={"impact": "high"}
)

# Impact analysis
impact = ims.graph.impact_analysis(
    entity_id=decision_node_id,
    entity_type="Decision"
)

暴露的资源

MCP服务器还公开只读资源以供检查/发现：

健康和能力

ims://health

- 运行时运行状况快照 session-memory, memory-core，以及 context-rag 可达性检查。

ims://capabilities

- 枚举服务器功能，包括工具/资源计数和可发现的工具/资源元数据。

会话快照

ims://sessions/{project_id}/open

- 使用从后端推断的用户上下文对项目的打开会话进行快照。

ims://sessions/{project_id}/{user_id}/open

- 显式项目和用户的打开会话的快照。

图形本体快照

ims://graph/{project_id}/drift

- 显示被取代决策后组件的架构漂移报告。

ims://graph/corrections/ready

- 已准备好推广的更正的全局快照（3次以上使用，尚未确认）。

ims://graph/{project_id}/corrections/ready

- 项目范围的更正已准备好推广到模式。

IMS后端更改（上下文标记）以利用新的文档语义

这 docs_index_directory 该工具（以及底层的分块/索引逻辑）现在将更丰富的每块元数据写入Meilisearch文档：

snippet （简短预览）
path （相对路径）
ext （文件扩展名不带点）
tags （从路径/扩展派生的简单标签）
user_id （所有者）

然而，IMS后端 上下文抹布 服务（背后的东西 POST /context/search)必须更新为 *使用* 文档检索期间的这些字段。具体来说，为了利用新的语义，您通常需要将IMS后端更新为：

为文档点击返回更好的预览

- 更喜欢 snippet 从Meilisearch而不是返回整个 content 块作为命中片段。 - 保持 content 可用于接地（在元数据中返回或作为单独的字段返回），但要避免淹没提示/UI。

支持文档过滤控件（ext/path/tags）

- 扩展文档部分 /context/search 请求接受可选筛选器，例如： - ext：排外主义（例如。 ["md","txt"] 或 ["cls","trigger"] Apex） - path_prefix：例如。 "docs/" - tags：例如。 ["terraform","yaml"] - 将这些映射到Meilisearch filter 表达式，依赖于 path, ext，以及 tags 被配置为可过滤属性。

有意处理Salesforce元数据模式

- 许多Salesforce存储库将详细元数据存储为 **/*-meta.xml索引器可以使用include glob来包含这些，但检索层可能希望： - 取消优先级或排除 *-meta.xml 默认情况下，除非查询提示需要元数据，或 - 应用 path/tags 目标元数据与源元数据的约定。

当文档数量增加时，保护相关性

- 分块+索引更多的文件类型大大增加了Meilisearch文档的数量。 - 考虑对文档点击进行轻微的后处理步骤，例如： - 重复数据消除结果 path （保持每个文件的最佳得分块），和/或 - 限制唯一编号 path 保持上下文多样性的价值观。

决定所有权/多用户范围

- 索引器存储 user_id。如果您希望对文档检索进行按用户隔离，IMS后端应可选择按以下方式进行筛选 user_id 当存在时。 - 若你们想要项目共享文档，请只过滤项目。

如果你想保持IMS后端接口的稳定，最小的有用更改是#1（使用 snippet)加上一个可选 ext 文档检索部分的过滤器。

前本体IMS迁移指南

如果您要从IMS的前本体版本升级，本节将解释发生了什么变化以及如何调整您的工作流程。

发生了什么变化

新增功能（完全向后兼容）：

图形操作（节点创建、关系、分析查询）
增强 context-rag 具有可选的图形扩展
通过以下方式存储决策/问题时自动创建图形节点 memory-core

无重大变化：

所有现有工具继续像以前一样工作
现有的 memory-core.store_memory 调用自动受益于图节点创建
现有的 context-rag.context_search 调用自动包含图形扩展（可以禁用）

对于现有用户

你不需要改变任何东西 继续像以前一样使用IMS。但是，您可以选择使用新功能：

1.增强的上下文搜索

前本体论：

# Pure vector similarity search
results = ims.context_rag.context_search(
    project_id="my-app",
    query="authentication flow",
    sources=["code", "docs", "memories"]
)

后本体论（默认行为，通过图关系增强）：

# Hybrid vector + graph search (automatically enabled)
results = ims.context_rag.context_search(
    project_id="my-app",
    query="authentication flow",
    sources=["code", "docs", "memories"],
    expand_graph=True,   # Default: enriches results with related entities
    graph_depth=2        # Default: traverse 2 relationship levels
)

要禁用图形扩展（恢复为纯矢量搜索）：

results = ims.context_rag.context_search(
    project_id="my-app",
    query="authentication flow",
    sources=["code"],
    expand_graph=False  # Disable graph for pure vector similarity
)

2.自动创建图形节点

前本体论：

# Just stored in Postgres + Qdrant
memory_id = ims.memory_core.store_memory(
    project_id="my-app",
    text="Use Redis for session state. Rationale: Low latency, TTL support.",
    kind="decision",
    tags=["architecture", "redis"]
)

后本体（自动图节点，无需更改代码）：

# Same call, now also creates Decision node in Neo4j graph
memory_id = ims.memory_core.store_memory(
    project_id="my-app",
    text="Use Redis for session state. Rationale: Low latency, TTL support.",
    kind="decision",  # Automatically creates Decision graph node
    tags=["architecture", "redis"]
)
# Backend now creates:
# - Memory record (Postgres + Qdrant embedding) - as before
# - Decision node (Neo4j graph) - NEW, enables relationships & impact analysis

3.新图形操作（选择加入）

现在，您可以显式创建关系并运行分析查询：

# Create explicit relationships between entities
ims.graph.create_relationship(
    from_id=decision_node_id,
    rel_type="affects",
    to_id=component_node_id,
    properties={"impact": "high"}
)

# Run impact analysis
impact = ims.graph.impact_analysis(
    entity_id=decision_node_id,
    entity_type="Decision"
)
print(f"This decision affects {len(impact['affected_components'])} components")

# Find blocking bugs
blocking = ims.graph.blocking_analysis(feature_id="auth-2fa")
print(f"{len(blocking['blocking_bugs'])} bugs block this feature")

迁移步骤

对于大多数用户：无需采取任何行动。 您现有的代码可以继续工作，并自动从图形增强中受益。

要充分利用本体特性：

了解自动图节点行为：

- kind="decision" → 创建决策节点 - kind="issue" → 创建Bug节点 - kind="fact"/"note" → 仅内存（无图形节点）

查看现有记忆：

- 存储在本体前的内存仅存在于Postgres+Qdrant中 - 新的记忆（后本体论）也会创建图节点 - 不需要迁移旧内存，除非你需要它们的图形关系

逐步采用图形操作：

- 从新决策的影响分析开始 - 在识别依赖关系时添加显式关系 - 规划要素时使用阻塞分析

如果需要，调整上下文搜索：

- 如果图展开返回的结果太多，请减少 graph_depth - 如果您需要纯矢量搜索，请设置 expand_graph=False

向后兼容性保证

所有前本体工具签名保持不变
默认行为与智能增强功能向后兼容
图形功能是可添加的，不会取代现有功能
如果需要，您可以通过参数禁用图形功能

性能特征

上下文搜索(`context-rag`)

仅矢量搜索（expand_graph=False）：

典型延迟：100-300ms（取决于Qdrant/Meilisearch集群大小）
按比例缩放：向量/文档数量、嵌入大小
最适合：关系无关紧要时的快速相似性搜索

混合向量+图搜索（expand_graph=True，默认值）：

典型延迟：200-800ms（矢量搜索+图遍历）
按以下比例缩放： graph_depth （每级增加~50-200ms），图形密度
最适合：包括相关实体的全面背景

建议：

对于探索性查询：使用混合搜索（默认）
对于特定的代码查找：使用 expand_graph=False 对于速度
限制 graph_depth 对于大多数查询，设置为1-2（默认值：2）
使用 graph_depth=3 仅用于深度依赖性分析

内存存储(`memory-core`)

前本体论（仅限内存）：

延迟：50-150ms（Postgres插入+Qdrant嵌入）

后本体（内存+图节点）：

延迟：100-250ms（Postgres+Qdrant+Neo4j节点创建）
创建图节点的额外开销约为50-100ms
kind="decision"/"issue" 产生图形开销
kind="fact"/"note" 保持本体前速度（无图节点）

建议：

间接费用可用于决策/问题跟踪（一次性成本）
对于高频事实存储，图创建的影响最小（事实不会创建节点）

图的运算

节点创建：

延迟：50-100ms（Neo4j写入）
缩放方式：节点属性计数、索引更新

关系创建：

延迟：50-100ms（Neo4j关系写入）
缩放方式：关系属性计数、图密度

分析查询（影响、阻塞、漂移）：

延迟：100-500ms（取决于图遍历深度和密度）
影响分析：深度2-3时通常为150-300ms
阻塞分析：通常为100-200ms（通常为浅图）
架构漂移：通常为200-500ms（扫描取代决策）

建议：

谨慎使用分析查询（不要在紧循环中）
尽可能缓存分析结果（不经常更改）
当结果较大时限制遍历深度

缩放注意事项

矢量存储（Qdrant）：

高效处理数百万矢量
为每个项目使用集合进行隔离
考虑对非常大的代码库进行分片

图形数据库（Neo4j）：

处理数百万个节点/关系
性能会随着非常密集的图形（每个节点有数千条边）而降低
策略性地使用关系类型来启用过滤遍历
索引频繁查询的属性（project_id、node_type）

文本搜索（Meilisearch）：

处理数百万份文档
将文档分块到约500-1000个标记，以获得最佳相关性
使用可过滤的属性（文本、标签、路径）来减少搜索空间

故障排除

图形操作失败

症状： ims.graph.create_node() 返回500错误

可能原因：

无法从IMS后端访问Neo4j后端
本体架构未初始化
node_type无效或缺少必需的属性

解决：

# 1. Check backend health
health = client.read_resource("ims://health")
print(health)  # Look for graph_db status

# 2. Verify node type is valid
# Valid types: Decision, Bug, Feature, Component, Correction, Reflection, Pattern, Lesson

# 3. Ensure required properties exist
node_id = ims.graph.create_node(
    node_type="Decision",
    properties={
        "text": "Required: decision description",
        "project_id": "Required: project identifier",
        "rationale": "Optional: why this decision"
    }
)

后端检查（如果您控制IMS后端）：

验证Neo4j是否正在运行： docker ps | grep neo4j 或查看Neo4j服务
检查Neo4j连接错误的后端日志
确认本体架构已初始化： MATCH (n) RETURN labels(n) LIMIT 10 在Neo4j浏览器中

上下文搜索不返回图形结果

症状： context_search() 仅返回向量结果，不进行图扩展

可能原因：

图形扩展已禁用： expand_graph=False
还不存在图节点（本体前数据）
与矢量搜索结果无关的图形实体

解决：

# 1. Explicitly enable graph expansion (default is True)
results = ims.context_rag.context_search(
    project_id="my-app",
    query="your query",
    sources=["memories"],  # Memories most likely to have graph nodes
    expand_graph=True,     # Explicitly enabled
    graph_depth=2          # Increase if needed
)

# 2. Check if graph nodes exist
from app.ims_client import IMSClient
ims = IMSClient()
try:
    # Attempt to query graph
    impact = ims.graph.impact_analysis(
        entity_id="any-decision-id",
        entity_type="Decision"
    )
    print("Graph backend is operational")
except Exception as e:
    print(f"Graph backend issue: {e}")

# 3. Store some decisions/issues to populate graph
ims.memory_core.store_memory(
    project_id="my-app",
    text="Use PostgreSQL for relational data",
    kind="decision",  # Creates Decision node
    tags=["database"]
)

本体升级后内存存储速度变慢

症状： store_memory() 需要200-300ms，而不是之前的100ms

说明： 这是预期的 kind="decision"/"issue" 由于图形节点的创建。不是虫子。

解决：

调整期望值： 创建图形节点会为决策/问题增加50-100ms的开销。这是实现关系和影响分析的成本。

对于非决策数据的高频存储：

   # Use kind="fact" or "note" to skip graph node creation
   ims.memory_core.store_memory(
       project_id="my-app",
       text="Log entry: request took 150ms",
       kind="fact",  # No graph node, faster
       tags=["performance"]
   )

批量操作： 如果存储了许多决策，请将相关决策分组，然后创建关系：

   # Store decisions
   decision_ids = []
   for decision_text in decisions:
       id = ims.memory_core.store_memory(
           project_id="my-app",
           text=decision_text,
           kind="decision"
       )
       decision_ids.append(id)

   # Create relationships in batch (future optimization)
   # Currently, relationships are created one at a time

连接超时

症状： httpx.ReadTimeout 或 TimeoutException

可能原因：

IMS后端过载或运行缓慢
遍历过多关系的图形查询
IMS后端的网络延迟

解决：

增加超时时间：

   export IMS_HTTP_TIMEOUT=10.0  # Default is 5.0 seconds

减少图遍历深度：

   results = ims.context_rag.context_search(
       project_id="my-app",
       query="query",
       sources=["memories"],
       expand_graph=True,
       graph_depth=1  # Reduce from default 2
   )

检查后端运行状况：

   health = client.read_resource("ims://health")
   # Look for slow response times or error status

无效的关系类型

症状： create_relationship() 失败，出现验证错误

有效关系类型：

implements （特征→ 决定）
blocks (Bug → 功能）
affects （决定→ 组件）
depends_on （组件→ 组件）
supersedes （决定→ 决定）
fixed_by (Bug → 决定）
worked_on （会议→ 功能/Bug）
addresses （更正→ Bug/问题）
inspired_by （图案→ 修正、反思）
learned_from （课程→ 错误、决策、反思）
documents （反思→ 会议/决定）
applied_to （图案→ 组件）
tagged_with (any → Tag)
relates_to （一般关系）
precedes （时间顺序）
contains （组成）

解决方案：

# Use valid relationship type
ims.graph.create_relationship(
    from_id=decision_id,
    rel_type="affects",  # Must be from list above
    to_id=component_id
)

获取帮助

先检查资源：

from mcp import ClientSession
import mcp.types as types
import asyncio

async def check_capabilities():
    # Connect to ims-mcp server and read capabilities
    # This shows all available tools and resources
    capabilities = await session.read_resource(
        types.ReadResourceRequest(
            uri="ims://capabilities"
        )
    )
    print(capabilities)

asyncio.run(check_capabilities())

常见问题：

后端无法访问： 检查 IMS_BASE_URL env-var，确保后端正在运行
SSL错误： 集 IMS_VERIFY_SSL=false 用于本地开发（非生产）
身份验证问题： IMS后端目前不需要身份验证；如果您看到身份验证错误，请检查您的 IMS_BASE_URL
过期缓存： 重新启动MCP服务器以清除所有客户端缓存

报告错误：

检查IMS后端日志是否有错误
包括失败的MCP工具调用（编辑敏感数据）
包括后端API响应（如果可用）
注意IMS后端版本和Neo4j版本

IMS MCP Server

快速接入

详细介绍

IMS MCP服务器

先决条件

安装（真空+管道）

配置

使用.env文件（本地开发）

直接设置变量

在本地运行MCP服务器

mcphub配置示例

外露工具

上下文检索

文档索引（Meilisearch）

长时程记忆

会话状态

跨项目交接

图操作（本体论）

客户端库使用情况

暴露的资源

健康和能力

会话快照

图形本体快照

IMS后端更改（上下文标记）以利用新的文档语义

前本体IMS迁移指南

发生了什么变化

对于现有用户

1.增强的上下文搜索

2.自动创建图形节点

3.新图形操作（选择加入）

迁移步骤

向后兼容性保证

性能特征

上下文搜索(context-rag)

内存存储(memory-core)

图的运算

缩放注意事项

故障排除

图形操作失败

上下文搜索不返回图形结果

本体升级后内存存储速度变慢

连接超时

无效的关系类型

获取帮助

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

上下文搜索(`context-rag`)

内存存储(`memory-core`)