使用说明

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后端。

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

组件	运行位置
PDF文件	仅限本地磁盘-从未上传
文本分块	本地Python进程
嵌入模型(`all-MiniLM-L6-v2`)	完全通过本地运行 `sentence-transformers`
FAISS矢量存储	仅在内存中，重建每个会话

你的机器还剩什么

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

后端	目的地	备注
奥拉玛	`localhost` only--完全离线	没有任何东西离开你的机器。最好用于机密文件。
克劳德（人类学）	`api.anthropic.com`	默认情况下，Anthropic不会在API数据上进行训练。看 anthropic.com/隐私
GitHub Copilot	Microsoft/Azure OpenAI	根据您的GitHub或企业协议
开放路由	`openrouter.ai` → 第三方模型主机	请求路由到外部提供程序。看 openrouter.ai/隐私

按敏感度级别推荐

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

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

更喜欢 奥拉玛 --什么都不会离开你的机器。
如果使用云，首选 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 <your-repo-url> 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

关键变量：

变量	描述
`LLM_BACKEND`	`claude`, `copilot`, `openrouter`，或 `ollama`
`ANTHROPIC_API_KEY`	从 console.anthropic.com
`ANTHROPIC_BASE_URL`	保持原样 `https://api.anthropic.com` --防止本地代理冲突
`GITHUB_TOKEN`	从 github/设置/令牌 --需求型号（阅读）范围
`OPENROUTER_API_KEY`	从 openrouter.ai/keys
`OLLAMA_MODEL`	例如。 `mistral:7b`
`PDF_PATH`	通往您的风格指南PDF的绝对路径

4.添加您的PDF

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

# macOS
PDF_PATH=<PATH>/style-guide.pdf

# Ubuntu / WSL2
PDF_PATH=<PATH>/style-guide.pdf

5.测试

make test

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

连接到克劳德桌面

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

macOS：

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

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

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

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

示例提示：

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

连接到VS代码

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

集成	工作原理	最适合
MCP聊天工具	Copilot Chat按需呼叫您的风格指南	提问、临时检查
VS代码扩展	右键单击以检查所选内容或完整文档	写作时主动进行样式检查

选项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": "<PATH>/mcp-styleguide/.venv/bin/python",
      "args": ["<PATH>/mcp-styleguide/server.py"]
    }
  }
}

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

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

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

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

提示： 如果已经配置了Claude Desktop，请跳过 .vscode/mcp.json 并在VS Code配置上启用自动发现：
"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自动启动程序）扩展。

要使用：

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

选项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

第三步——使用它

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

行动	可用时	它的作用
样式指南：检查选择	已选择文本	仅检查所选文本
样式指南：检查完整文档	始终	检查整个打开的文件
风格指南：提问	始终	打开输入框，将问题发送到 `/ask`

状态栏 （右下角）：单击 $(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+,):

设置	默认值	说明
`styleGuide.serverUrl`	`http://localhost:5123`	HTTP服务器的URL
`styleGuide.timeoutMs`	`180000`	请求超时（毫秒）。对于速度较慢的Ollama型号，请求超时时间会增加。

扩展故障排除

状态栏显示 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.拉一个模型

RAM	型号	命令
8 GB	`mistral:7b` （快速、格式良好）	`ollama pull mistral:7b`
8 GB	`llama3.1:8b` （备选）	`ollama pull llama3.1:8b`
16GB	`mistral-small3.1:7b` （以下为最佳说明）	`ollama pull mistral-small3.1:7b`
32GB+	`llama3.3:70b` （最高质量）	`ollama pull llama3.3:70b`

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

设置：

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

示例提示：

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

格式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 <your-project-root>/CLAUDE.md

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

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

如果 ~/.claude/CLAUDE.md 已存在，请追加而不是覆盖：
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.ai项目	claude.ai浏览器	每次对话	非开发人员，快速检查
CLAUDE.md（项目）	Claude Code	是的，在那个项目中	团队——在仓库中共享
CLAUDE.md（全球）	克劳德代码	是的，无处不在	个人全球风格规则
~/.claude/技能/	Claude Code	否-按需提供	多种风格指南，精简上下文
MCP服务器+扩展	Claude Desktop，VS Code	按需	开发人员，VS Code右键单击检查

提示——将它们结合起来： 使用 ~/.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

调谐

`.env` 变量	默认值	效果
`RETRIEVER_K`	`5`	每次查询检索到的PDF块。更高=更广泛的背景。
`CHUNK_SIZE`	`1000`	每块字符数。更小=更精确的检索。
`CHUNK_OVERLAP`	`200`	块之间的重叠——防止在边界处切割上下文。
`EXTRA_CONTEXT`	（空）	在提示中注入业务部门专业化，例如。 `"You are reviewing content for a financial services audience."`

故障排除

找不到PDF → 使用绝对路径： PDF_PATH=<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/....

使用说明

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

运作原理

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

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

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

隐私和数据安全

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

你的机器还剩什么

按敏感度级别推荐

项目结构

设置

先决条件

1.获得项目

2.安装依赖项

3.配置 .env

4.添加您的PDF

5.测试

连接到克劳德桌面

连接到VS代码

选项A-MCP聊天工具

选项B--VS代码扩展

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

步骤1--启动HTTP服务器

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

第三步——使用它

扩展设置

扩展故障排除

与Ollama完全离线运行

1.安装Olama

2.启动Olama

3.拉一个模型

4.配置 .env

5.测试

从PDF生成技能

格式1--第.ai条项目

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

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

使用哪种格式？

保持技能更新

切换后端

调谐

故障排除

相关 MCP

PDF处理工具集

PDF文本提取服务

PDF阅读工具

学术资源访问服务

文本增强工具

韩语拼写检查服务

3.配置 `.env`

4.配置 `.env`

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

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