AI导哈

交互式文档管理服务

MCP交互式指令服务器，支持AI代理自主管理文档（创建草稿、组织知识、经用户批准后提升为确认文档）。

  • by dbgso
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 dbgso/mcp-interactive-instruction

使用说明

mcp交互式教学

用于交互式指令文档的MCP服务器。使AI代理能够自主管理文档——创建草稿、组织知识，并在用户批准的情况下推广到已确认的文档。

为什么

加载大型.md文件的传统方法（如 agents.md, skills.md)在对话开始时有局限性：

  • 上下文膨胀：即使不需要，所有文档也会占用上下文空间
  • 遗忘：随着对话的增长，人工智能逐渐“忘记”早期加载的内容
  • 全有或全无：无法选择性地刷新特定信息
  • 静态知识：人工智能无法记录对话中的新知识

该工具通过以下方式解决了这些问题：

  • 基于主题的拆分：按主题将文档组织到单独的文件中
  • 按需检索：只在需要的时候取需要的东西
  • 互动式召回：AI可以通过查询MCP工具“记住”信息
  • 自主学习：AI可以在未经许可的情况下将新知识记录为草稿
  • 人为监督：草稿在成为确认文件之前需要批准

工具

工具 目的 权限
description 显示所有工具的使用说明 -
help 浏览/阅读已确认的文档 -
draft 临时文档的CRUD(_mcp_drafts/) AI可以自由使用
apply 将草稿升级为确认文档 需要用户批准

描述

显示所有MCP工具的详细使用说明。

description()
→ Full usage guide with examples

帮助

浏览并阅读已确认的文档。草稿(_mcp_drafts/)被自动过滤掉。

# List root level (shows categories and documents)
help()

# Navigate into a category
help({ id: "git" })

# Get specific document content
help({ id: "git__workflow" })

# List ALL documents at once (flat view)
help({ recursive: true })

草案

管理临时文件草稿。 AI应该自由地使用它 以记录从用户指令中学到的任何新信息。

# Show draft tool help
draft()

# List all drafts
draft({ action: "list" })

# Read a draft
draft({ action: "read", id: "coding__style" })

# Create new draft (NEW topic = NEW file!)
draft({ action: "add", id: "coding__testing", content: "# Testing Rules\n\n..." })

# Update existing draft (same topic only)
draft({ action: "update", id: "coding__testing", content: "# Testing Rules\n\nUpdated..." })

# Delete a draft
draft({ action: "delete", id: "old-draft" })

# Rename/move a draft (safe reorganization)
draft({ action: "rename", id: "old-name", newId: "category__new-name" })

AI的重要规则：

  • 新信息=新文件：不同主题=始终使用 add，不 update
  • 每个文件一个主题：使每个草稿都集中在一个主题上
  • 使用层次结构：使用前缀对相关主题进行分组（例如。， coding__testing)

应用

将草稿升级为已确认的文件。这需要用户批准。

# Show apply tool help
apply()

# List drafts ready to promote
apply({ action: "list" })

# Promote a draft (same name)
apply({ action: "promote", draftId: "coding-style" })
→ Moves _mcp_drafts/coding-style.md to coding-style.md

# Promote with different name/location
apply({ action: "promote", draftId: "temp-guide", targetId: "guides__setup" })
→ Moves _mcp_drafts/temp-guide.md to guides/setup.md

安装

npm install -g mcp-interactive-instruction

或者直接与npx一起使用：

npx mcp-interactive-instruction /path/to/docs

配置

克劳德代码

增添 ~/.claude/settings.json 对于全局配置：

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-instruction", "/path/to/your/docs"]
    }
  }
}

或创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-instruction", "./docs"]
    }
  }
}

提醒标志（可选）

可选地添加标志，以帮助AI记住使用MCP工具：

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-interactive-instruction",
        "./docs",
        "--remind-mcp",
        "--remind-organize",
        "--reminder", "Always check tests before committing"
      ]
    }
  }
}
标志 效果
--remind-mcp 提醒AI在开始任务之前检查文档
--remind-organize 提醒AI保持文档有序（每个文件一个主题）
--reminder <message> 添加自定义提醒消息（可多次使用）
--topic-for-every-task <id> 指定AI在执行每个任务之前必须重新阅读的文档
--info-expires <seconds> MCP信息的有效期（默认值：60）。使用 --topic-for-every-task

每个任务的主题

强制AI在执行每个任务之前重新阅读特定文档。这对于永远不应忘记的关键规则非常有用：

{
  "args": [
    "-y",
    "mcp-interactive-instruction",
    "./docs",
    "--topic-for-every-task", "topic-for-every-task",
    "--info-expires", "60"
  ]
}

这 --info-expires 标志告诉AI MCP信息在N秒后过期，需要刷新。这会触发在执行每个任务之前重新读取指定的文档。

最佳实践： 将每个任务文档的主题作为 重定向中心 而不是详细的规则列表：

# Topic for Every Task

Read these documents before starting any task:

- `why-this-project` - Project concept and goals
- `coding-rules` - Essential coding conventions

## Quick Reminders
- Use params object style for function arguments
- All documentation must be in English

这种方法使文档保持轻量级，同时确保AI始终知道要检查哪些主题。

调谐 --info-expires: 更短的到期时间会导致更频繁的重新读取，确保规则永远不会被遗忘。然而，这会消耗更多的上下文空间。根据您的需求进行调整：

价值 效果
30-60s 频繁重读，上下文使用率更高
120-300s 平衡方法
600s+ 很少重读，上下文使用率较低

注： 此功能会影响AI行为，但不能保证100%的合规性。人工智能仍然可以根据上下文和任务要求自主决定何时重新阅读文档。

带有多个自定义提醒的示例：

{
  "args": [
    "-y",
    "mcp-interactive-instruction",
    "./docs",
    "--reminder", "Run tests after code changes",
    "--reminder", "Use Japanese for commit messages"
  ]
}

目录结构

docs/
├── coding-style.md              → id: "coding-style" (confirmed)
├── git/
│   ├── workflow.md              → id: "git__workflow" (confirmed)
│   └── commands.md              → id: "git__commands" (confirmed)
└── _mcp_drafts/                 ← AI's temporary drafts
    ├── new-feature.md           → draft id: "new-feature"
    └── coding/
        └── testing.md           → draft id: "coding__testing"
  • 已确认的文档：根级别和子目录（不包括 _mcp_drafts/)
  • 草稿：存储在 _mcp_drafts/ 目录
  • ID格式：使用 __ （双下划线）作为路径分隔符

工作流程

对于人工智能

  1. 任务前检查文档：使用 help() 查看可用文档
  2. 记录新的学习成果：当用户教授新内容时，立即创建草稿
  3. 每个文件一个主题：保持草稿的重点和粒度
  4. 推广前先问：使用前获得用户批准 apply
# User says: "Always use params object style for function arguments"
draft({ action: "add", id: "coding__params-style", content: "# Params Style\n\n..." })

# Later, ask user: "Should I promote this to confirmed docs?"
apply({ action: "promote", draftId: "coding__params-style" })

对于用户

  1. 审阅草稿：检查 draft({ action: "list" }) 查看AI记录了什么
  2. 批准或拒绝：决定哪些草稿应成为永久性文件
  3. 组织：使用 apply 随着 targetId 将文档放置在正确的位置

文档格式

# Title

Summary paragraph that appears in the document list.

## Section 1

Content...

第一段之后 # Title 标题用作列表中的摘要。 进行描述性总结 因此AI可以识别每个文档何时相关。

粒度指南

让每个文档都专注于 一个主题:

|而不是分裂成| |------------|------------| | git.md （一切）| git__workflow.md + git__commands.md | | coding.md （所有规则）| coding__style.md + coding__testing.md |

为什么这很重要：

  • AI只加载需要的东西
  • 更容易查找和更新特定信息
  • 更好的匹配摘要

演出

  • 缓存：文档列表缓存1分钟
  • 缓存失效：自动写操作
  • 延迟加载：文件仅在要求时才可阅读

许可证

麻省理工学院

相关 MCP