oratio (Fm4tt0s)

Oratio-MCP服务器的写作风格指南

MCP服务器，可将您的企业写作风格指南PDF转换为您可以从中查询的AI专家 克劳德桌面, VS Code，或直接在 claude.ai.支持 克劳德, GitHub Copilot, 开放路由，以及 奥拉玛 （完全本地）作为LLM后端——可通过单线输入进行切换 .env.

工作在 macOS, 乌班图，以及 Windows通过WSL2.

______________________________________________________________________

运作原理

该项目有三种不同的使用模式。每个引擎都基于相同的RAG引擎，但暴露方式不同。

模式1-MCP服务器（克劳德桌面/VS代码聊天）

Your question
      │
      ▼
Claude Desktop or VS Code Copilot Chat
      │  MCP protocol
      ▼
server.py  (MCP server)
      │
      ▼
rag.py  (RAG engine)
  ├── PyPDF  →  loads and chunks the PDF
  ├── FAISS  →  finds relevant chunks via semantic search
  └── LLM    →  Claude / Copilot / OpenRouter / Ollama
      │
      ▼
Answer + source page numbers

模式2--VS代码扩展（右键单击样式检查）

两个进程必须同时运行：

VS Code (right-click → Check Selection)
      │  HTTP POST /check
      ▼
server_http.py  (lightweight HTTP server, port 5123)
      │
      ▼
rag.py  (RAG engine — same as above)
      │
      ▼
LLM  (whichever backend is set in .env)
      │
      ▼
Results shown in Output panel + squiggles in editor

因此，您需要运行两个终端：

• 1号航站楼： ollama serve （如果使用Ollama，可以改为后台服务）
• 2号航站楼： make server-http

模式3-Claude.ai项目（无需服务器）

make skill
      │
      ▼
generate_skill.py
  ├── Extracts text from PDF
  └── LLM generates a system prompt summarising all rules
      │
      ▼
skill_output/system_prompt.md  ← paste into Claude.ai Project Instructions
skill_output/INSTRUCTIONS.md   ← setup guide

Then in claude.ai:
  Project Instructions (system prompt) + PDF uploaded as knowledge
      │
      ▼
Claude answers style questions natively — no server needed

第一次在模式1或2中运行查询时，PDF会被加载、分块并嵌入内存中的FAISS向量存储中。同一会话中的后续查询很快，因为存储被重用。

______________________________________________________________________

隐私和数据安全

简短回答： 您的PDF永远不会作为文件离开您的机器。但是，其文本的小片段会作为每个查询提示的一部分发送到您选择的LLM后端。

什么留在你的机器上——总是

你的机器还剩什么

当您提出问题或检查文本时，RAG引擎会检索最相关的PDF块（约5-8段，每段约1000个字符），并将其与您的查询一起发送给LLM。这些是纯文本摘录，而不是PDF本身。

按敏感度级别推荐

公共或内部风格指南 --任何后端都可以。

机密风格指南 （未发布的产品名称、法律语言、限制术语）：

• 更喜欢 奥拉玛 --什么都不会离开你的机器。
• 如果使用云，首选 API克劳德 或 GitHub Copilot 根据企业协议。
• 避免 OpenRouter免费版 对于敏感内容。
• 考虑减少 RETRIEVER_K 在 .env （例如 3)限制每次查询发送的摘录。

高度受限 （不能离开公司网络）：

• 使用 奥拉玛 --看 与Ollama完全离线运行.

______________________________________________________________________

项目结构

mcp-styleguide/
├── server.py              # MCP server — for Claude Desktop and VS Code Chat
├── server_http.py         # HTTP server — for the VS Code extension
├── rag.py                 # RAG engine shared by all modes
├── generate_skill.py      # Generates a Claude.ai Project system prompt
├── requirements.txt       # Python dependencies
├── Makefile               # Commands: install, test, server, server-http, skill
├── env.example            # Config template — copy to .env
├── skill_output/          # Generated by `make skill`
│   ├── [...]              # To be defined as per skill creation
├── vscode/                # VS Code extension
│   ├── [...].             # VS Code extension source files
└── your-style-guide.pdf   ← set PDF_PATH in .env to point here

______________________________________________________________________

设置

先决条件

macOS：

brew install python@3.13
xcode-select --install   # provides make

Ubuntu/WSL2：

sudo apt update && sudo apt install -y python3 python3-pip python3-venv make

WSL2注释： 在WSL终端内运行以下所有命令。将项目文件保存在WSL文件系统中(/home/...)--不在 /mnt/c/... --以避免跨文件系统I/O速度慢。

______________________________________________________________________

1.获得项目

git clone  mcp-styleguide
cd mcp-styleguide

2.安装依赖项

make install

这创造了 .venv/ 使用最好的Python（3.13→3.12→3）并安装所有依赖项。如果需要，请覆盖：

make install PYTHON=python3.12

3.配置 .env

cp .env.example .env

关键变量：

4.添加您的PDF

集 PDF_PATH 在 .env 转到PDF的绝对路径：

# macOS
PDF_PATH=
/style-guide.pdf

# Ubuntu / WSL2
PDF_PATH=
/style-guide.pdf

5.测试

make test

您应该看到PDF加载、块创建、嵌入生成和测试答案打印。

______________________________________________________________________

连接到克劳德桌面

打开克劳德桌面→ 设置 → 开发者 → 编辑配置 并添加：

macOS：

{
  "mcpServers": {
    "writing-style-guide": {
      "command": "
/mcp-styleguide/.venv/bin/python",
      "args": ["
/mcp-styleguide/server.py"]
    }
  }
}

Ubuntu/WSL2 （Claude Desktop在Windows上运行，服务器在WSL中运行）：

{
  "mcpServers": {
    "writing-style-guide": {
      "command": "wsl.exe",
      "args": ["--", "/mcp-styleguide/.venv/bin/python",
               "/mcp-styleguide/server.py"]
    }
  }
}

保存并重新启动Claude Desktop。你应该看到一个 连接器 聊天中的菜单（在“+”符号下），以及 写作风格指南 在那里。

示例提示：

• *“我可以在文档中使用‘不能’吗？检查写作风格规则。”*
• *“我应该如何根据我们的风格指南格式化IP地址？”*
• *“我们的文档中是否批准了‘主/从’一词？”*

______________________________________________________________________

连接到VS代码

有两个单独的VS Code集成。选择一个或同时使用两个。

______________________________________________________________________

选项A-MCP聊天工具

创建 .vscode/mcp.json 在项目根目录中或编辑 ~/Library/Application Support/Code/User/mcp.json 使其可用于用户级别的任何项目。

提示：您也可以使用 Cmd+Shift+P （MacOS）/ Ctrl+Shift+P （Windows/Linux）并搜索 MCP: Open User Configuration 打开全局用户的MCP json配置文件。

macOS：

{
  "servers": {
    "writing-style-guide": {
      "command": "
/mcp-styleguide/.venv/bin/python",
      "args": ["
/mcp-styleguide/server.py"]
    }
  }
}

Ubuntu/WSL2——WSL内部运行的VS代码 （通过远程WSL扩展）：

{
  "servers": {
    "writing-style-guide": {
      "command": "/mcp-styleguide/.venv/bin/python",
      "args": ["/mcp-styleguide/server.py"]
    }
  }
}

Ubuntu/WSL2——在Windows上运行的VS代码：

{
  "servers": {
    "writing-style-guide": {
      "command": "wsl.exe",
      "args": ["--", "/mcp-styleguide/.venv/bin/python",
               "/mcp-styleguide/server.py"]
    }
  }
}

提示： 如果已经配置了Claude Desktop，请跳过 .vscode/mcp.json 并在VS Code配置上启用自动发现： ``json "chat.mcp.gallery.enabled": true, "chat.mcp.discovery.enabled": true ``

提示：每次都需要启动MCP，您可以通过 MCP: List Servers → writing-style-guide → Start Server。有一个实验性的配置设置，可以在启动VS Code时自动启动它，请转到 Settings → Settings → chat.mcp.autostart 并将其设置为 newAndOutdated.

我在MacOS上没有成功，尽管我成功地使用了\[MCP Auto Starter\]https://marketplace.visualstudio.com/items?itemName=alankyshum.vscode-mcp自动启动程序）扩展。

要使用：

1. 打开Copilot聊天(Cmd+Shift+I / Ctrl+Shift+I)
2. 切换至 代理模式
3. 点击“+”符号→ 工具→ 写作风格指南：所有工具

______________________________________________________________________

选项B--VS代码扩展

这使您可以在编辑器中直接右键单击样式检查。结果显示在 输出面板 正如冒犯性文本上波浪般的下划线。

它是如何工作的（通信流）

VS Code editor
  └─ right-click → "Style Guide: Check Selection"
        │  HTTP POST /check  { "text": "..." }
        ▼
server_http.py  running on localhost:5123
        │
        ▼
rag.py  (loads PDF, searches FAISS, calls LLM)
        │
        ▼
LLM  (Ollama / Claude / OpenRouter / Copilot)
        │
        ▼
JSON response  { verdict, issues[], summary }
        │
        ▼
VS Code  →  Output panel (full report)
         →  Squiggles on offending text
         →  Status bar  ✗ 1 fail, 2 warn

步骤1--启动HTTP服务器

# In a dedicated terminal — keep it running while you work
make server-http

预期产量：

Style Guide HTTP server starting on http://localhost:5123
Endpoints: POST /check  POST /ask  GET /health

如果使用Olama，请确保它也在运行(ollama serve 或者作为系统服务）启动HTTP服务器之前。

步骤2——构建并安装扩展

Ubuntu必备条件： sudo apt install -y nodejs npm MacOS先决条件： brew install node

cd vscode
npm install && npm run compile
npm run package    # compiles TypeScript and produces style-guide-checker-0.2.0.vsix

在VS代码中安装（推荐）

Cmd+Shift+P / Ctrl+Shift+P  →  Extensions: Install from VSIX  →  select the .vsix file

或者用于开发（无需安装，重新编译时重新加载）：

npm install && npm run compile
# Open the vscode/ folder in VS Code and press F5

第三步——使用它

右键菜单 （首先选择文本以查看“检查选择”）：

状态栏 （右下角）：单击 $(book) Style Guide 随时查看完整文档。

结果：

• 输出面板 （“风格指南”频道）自动打开，显示完整报告：判决、每个问题的违规摘录和建议修复、页面参考和摘要
• 弯曲线条 出现在违反规则的单词上——红色代表 FAIL，黄色为 WARN
• 悬停 通过曲线图查看规则并内联修复

命令面板 (Cmd+Shift+P / Ctrl+Shift+P):

• Style Guide: Check Selection
• Style Guide: Check Full Document
• Style Guide: Ask a Question
• Style Guide: Clear All Diagnostics

扩展设置

搜索 styleGuide 在VS代码设置中(Cmd+, / Ctrl+,):

扩展故障排除

状态栏显示 Server Offline → Run make server-http 在终端中并保持其打开状态。

右键菜单不显示样式指南项 → 重新加载VS代码(Cmd+Shift+P → 开发者：重新加载窗口)在安装VSIX之后。

“检查选择”显示为灰色 → 您需要先选择文本——该命令仅在有活动选择时出现。

超时错误 → 增加 styleGuide.timeoutMs 在设置中（例如 300000 对于速度较慢的Olama车型），或切换到速度较快的车型，如 mistral:7b.

______________________________________________________________________

与Ollama完全离线运行

Ollama完全在您的机器上运行LLM-没有API密钥，初始模型下载后没有互联网，没有数据离开您的计算机。

1.安装Olama

macOS： brew install ollama

Ubuntu/WSL2： curl -fsSL https://ollama.com/install.sh | sh

WSL2:GPU加速与NVIDIA GPU+WSL2驱动程序配合使用。没有GPU，Ollama在CPU上运行——速度较慢但功能正常。

2.启动Olama

macOS： ollama serve 或 brew services start ollama

Ubuntu： ollama serve 或 sudo systemctl start ollama

WSL2： ollama serve &

3.拉一个模型

对于样式指南的使用（结构化输出、规则遵循、引用） 密史脱拉风 家庭产生更清洁的结果。从...开始 mistral:7b.

4.配置 .env

LLM_BACKEND=ollama
OLLAMA_MODEL=mistral:7b
OLLAMA_BASE_URL=http://localhost:11434

5.测试

make test
# Expected: Using backend: Ollama (mistral:7b) -> http://localhost:11434

笔记：

• 第一个查询将模型加载到内存中（~60-90s）。后续查询应该更快。
• Ollama之前一定在跑步 make server 或 make server-http.
• 如果答案似乎被切断了，请添加 OLLAMA_NUM_CTX=8192 到 .env.

______________________________________________________________________

从PDF生成技能

make skill 读取您的PDF并生成 三种不同的技能形式 一次性完成——每个环境对应一个：

make skill

输出：

skill_output/
├── system_prompt.md                    ← Claude.ai Project instructions
├── INSTRUCTIONS.md                     ← setup guide for the above
├── CLAUDE.md                           ← Claude Code instruction file
└── writing-style-guide-skill/
    └── SKILL.md                        ← reusable Claude Code skill

______________________________________________________________________

格式1--第.ai条项目

最简单的选择——没有服务器，没有CLI，只需在浏览器中claude.ai。

设置：

1. 首选 claude.ai → 项目 → 创建项目
2. 点击 编辑项目说明 → 粘贴以下内容 skill_output/system_prompt.md
3. 点击 添加内容 → 上传您的风格指南PDF
4. 完成——项目中的每一次对话现在都具有风格指南意识

示例提示：

• *“我可以在文档中使用‘不能’这样的缩写吗？”*
• *“检查此段落是否违反样式：\[粘贴文本\]”*
• *“重写此内容以符合我们的风格指南：\[粘贴句子\]”*

______________________________________________________________________

格式2--克劳德代码 CLAUDE.md

CLAUDE.md 是Claude Code在每个会话开始时自动读取的Markdown文件。将其放置在项目根目录中以获取项目范围的规则，或放置在 ~/.claude/ 将其应用于全球所有项目。

Claude Code session starts
        │
        ▼
Reads CLAUDE.md (project root, then ~/.claude/)
        │
        ▼
Claude already knows your style rules before you type anything

项目级别 （仅适用于在该项目中工作时）：

cp skill_output/CLAUDE.md /CLAUDE.md

全球 （适用于所有Claude Code会话）：

cp skill_output/CLAUDE.md ~/.claude/CLAUDE.md

如果 ~/.claude/CLAUDE.md 已存在，请追加而不是覆盖： ``bash cat skill_output/CLAUDE.md >> ~/.claude/CLAUDE.md ``

一旦就绪，只要您要求Claude Code编写、审阅或编辑文档，它就会自动应用样式指南，而不需要额外的提示。

______________________________________________________________________

格式3--克劳德代码技能(~/.claude/skills/)

技能是一种可重用的命名能力，Claude Code可以根据需要显式加载。不像 CLAUDE.md 当任务与其描述相匹配时，会参考一项技能——对于不需要样式检查的会话，保持上下文简洁。

Claude Code session
        │
        ▼
You ask: "Check this doc for style issues"
        │
        ▼
Claude sees skill description matches → loads SKILL.md into context
        │
        ▼
Applies style rules from the skill to your text

安装：

cp -r skill_output/writing-style-guide-skill ~/.claude/skills/

验证它是否可用 通过启动Claude Code会话并询问：

What skills do you have available?

你应该看看 writing-style-guide 上市的。

用法 --Claude Code将在相关时自动加载它，或者您可以显式引用它：

Use the writing-style-guide skill to review this paragraph: [paste text]

______________________________________________________________________

使用哪种格式？

提示——将它们结合起来： 使用 ~/.claude/skills/ 具备一般克劳德代码工作的技能，以及MCP服务器+VS代码扩展，用于在编写时进行实时检查。他们都阅读相同的PDF，并使用相同的RAG引擎。

______________________________________________________________________

保持技能更新

重新运行 make skill 每当PDF发生变化时，它都会同时重新生成所有三种格式。然后将更新的文件复制到安装它们的任何位置。

______________________________________________________________________

切换后端

更改一行 .env 并重新启动服务器：

LLM_BACKEND=claude       # Anthropic Claude API
LLM_BACKEND=copilot      # GitHub Copilot (OpenAI-compatible)
LLM_BACKEND=openrouter   # OpenRouter (free & paid models)
LLM_BACKEND=ollama       # Fully local — nothing leaves your machine

______________________________________________________________________

调谐

______________________________________________________________________

故障排除

找不到PDF → 使用绝对路径： PDF_PATH= /style-guide.pdf

ModuleNotFoundError 首次运行 → Use make test --它总是召唤 .venv/bin/python.如果手动运行： .venv/bin/python rag.py

已安装但未找到的包（多个Python版本） → make reinstall --清晰地再现了venv。

连接到错误的主机/ ANTHROPIC_BASE_URL 被忽视 → Add ANTHROPIC_BASE_URL=https://api.anthropic.com 到 .env.代码使用 load_dotenv(override=True) 所以 .env 总是胜过shell环境变量。

GITHUB_TOKEN 未设置/副本401 → 在github上生成一个令牌 模型 读取范围。

Ollama：连接被拒绝 → Run ollama serve在WSL2上： ollama serve & 在WSL终端中。

奥利玛：答案被切断了 → Add OLLAMA_NUM_CTX=8192 到 .env 并重新启动。

第一次查询速度慢 → 普通——首次使用时嵌入PDF。从第二次查询开始快速。

克劳德桌面：否🔧 图标 → 配置中的Python路径必须指向 .venv/bin/python关于WSL2的使用 wsl.exe 作为命令。

VS代码扩展名：服务器脱机 → make server-http 必须在单独的终端中运行。

VS代码扩展名：选中所选内容显示为灰色 → 首先选择文本——该命令仅在活动选择时显示。

WSL2： make 未找到 → sudo apt install -y make

WSL2：性能缓慢 → 将文件保存在 /home/... 不 /mnt/c/....