Tailwind Svelte Assistant MCP 服务器

这是一个安全、高性能的模型上下文协议（MCP）服务器，提供 完整的 SvelteKit 和 Tailwind CSS 文档（100% 覆盖）及代码片段，具有增强的安全性、正确的 TypeScript 实现和全面的错误处理。

✨ 新特性 (v0.1.1)

📚 完整文档覆盖

• 100% Svelte/SvelteKit 覆盖：官方 LLM 优化文档（1.04 MB）
• 100% Tailwind CSS 覆盖：通过 Repomix 提取的完整文档（2.1 MB，249 个文件）
• 智能搜索：在完整文档中进行带有上下文的搜索
• 12.5x-25x 改进：从 4-8% 覆盖到 100% 覆盖

🚀 关键改进 (v0.1.1)

🔒 安全增强

• 路径遍历保护：全面的输入清理防止目录遍历攻击
• 输入验证：严格的参数验证，包括模式匹配和长度限制
• 安全文件操作：带路径验证和大小限制的有界文件访问
• 审计日志：用于监控的结构化安全事件日志

🏗️ 架构改进

• 模块化设计：将关注点分离到专用的服务和工具中
• TypeScript 优秀实践：完全类型安全，使用正确的接口，不使用 any 类型
• ES 模块：现代 JavaScript 模块系统，使用正确的导入
• 错误处理：全面的错误分类和安全的错误消息

⚡ 性能优化

• 内容缓存：带有可配置超时的 LRU 缓存，以提高响应时间
• 文件大小限制：带有可配置限制的资源耗尽预防
• 异步操作：非阻塞文件操作以提高并发性
• 内存管理：自动缓存清理和垃圾回收

📁 项目结构

src/
├── index.ts                 # 带有安全加固的主服务器
├── types.ts                 # TypeScript 类型定义
├── services/
│   └── fileService.ts       # 带缓存的安全文件操作
└── utils/
    ├── security.ts          # 输入验证和路径清理
    └── errorHandler.ts      # 全面的错误处理

🚀 快速开始

通过 Smithery 安装（推荐）

安装此 MCP 服务器最简单的方法是通过 Smithery：

npx -y @smithery/cli install @CaullenOmdahl/tailwind-svelte-assistant --client claude

这将自动：

• 安装服务器
• 配置 Claude Desktop
• 设置所有必需的依赖项

通过直接 URL 安装

对于其他 MCP 客户端，使用直接服务器 URL：

https://server.smithery.ai/@CaullenOmdahl/tailwind-svelte-assistant/mcp

将其添加到您的 MCP 客户端配置中：

{
  "mcpServers": {
    "tailwind-svelte-assistant": {
      "url": "https://server.smithery.ai/@CaullenOmdahl/tailwind-svelte-assistant/mcp",
      "transport": "http"
    }
  }
}

🛠️ 手动安装与设置

前提条件

• Node.js 20+（需要支持 ES 模块和依赖项）
• npm 或 yarn
• Git（用于克隆仓库）

安装依赖项

npm install

构建服务器

npm run build

开发模式

npm run watch

🔧 配置

服务器使用安全默认值，但可以通过 ServerConfig 接口进行配置：

const CONFIG: ServerConfig = {
  maxFileSize: 3 * 1024 * 1024,    // 3MB 最大文件大小（用于完整文档）
  cacheTimeout: 5 * 60 * 1000,     // 5 分钟缓存超时
  contentBasePath: './content',
  svelteFullDocsPath: './content/docs/svelte-sveltekit-full.txt',
  tailwindFullDocsPath: './content/docs/tailwind-docs-full.txt',
  // ... 其他路径
};

文档更新

文档会自动下载并更新：

# 更新所有文档（Svelte + Tailwind）
npm run update-content

此脚本：

• 下载官方 Svelte LLM 优化文档（svelte.dev/llms-full.txt）
• 通过 Repomix 从 GitHub 提取完整的 Tailwind 文档
• 更新组件片段的时间戳
• 生成内容摘要

来源：

• Svelte/SvelteKit：官方 LLM 优化文本文件（100% 覆盖）
• Tailwind CSS：通过 Repomix 提取的 GitHub 仓库（249 个 MDX 文件）
• 片段：本地策划的组件示例（43 个文件）

🛡️ 安全特性

输入验证

• 模式匹配：仅允许字母数字、连字符、下划线和点
• 长度限制：可配置的最大输入长度
• 路径清理：移除目录遍历尝试
• 边界检查：确保文件访问在允许的目录内

错误处理

• 安全错误消息：不会向客户端暴露敏感信息
• 结构化日志：用于安全监控的 JSON 格式审计日志
• 错误分类：不同类型的错误有不同的处理方式
• 优雅降级：非关键故障的回退响应

文件系统安全

• 路径验证：验证解析路径是否在基目录内
• 文件大小限制：防止资源耗尽攻击
• 只读操作：不向客户端暴露写操作
• 缓存隔离：内容缓存不会暴露文件系统结构

📊 性能特性

缓存系统

// 自动内容缓存，带有可配置超时
const fileService = new SecureFileService(
  1024 * 1024,    // 最大文件大小
  5 * 60 * 1000   // 缓存超时（5 分钟）
);

资源管理

• 内存限制：文件大小限制防止内存耗尽
• 缓存清理：自动移除过期的缓存条目
• 异步 I/O：非阻塞文件操作
• 错误恢复：资源限制的优雅处理

🔍 可用工具

🆕 完整文档工具（推荐）

• get_svelte_full_docs - 获取完整的 Svelte & SvelteKit 文档（1MB，100% 覆盖）

  • 不需要参数
  • 返回整个 LLM 优化的文档文件
  • 官方格式来自 Svelte 团队

• get_tailwind_full_docs - 获取完整的 Tailwind CSS 文档（2.1MB，100% 覆盖）

  • 不需要参数
  • 包含所有 249 个文档文件
  • 覆盖所有实用类和概念

• search_svelte_docs - 在 Svelte/SvelteKit 文档中搜索

  • 参数：query（字符串），limit（可选，默认：5）
  • 返回带有上下文的匹配部分
  • 快速的内存搜索

• search_tailwind_docs - 在 Tailwind CSS 文档中搜索

  • 参数：query（字符串），limit（可选，默认：5）
  • 返回带有上下文的匹配部分
  • 覆盖所有实用类

旧版文档工具

注意：这些工具仅覆盖约 4-8% 的可用文档。使用上面的完整文档工具以获得完整覆盖。

• get_sveltekit_doc - 获取特定的 SvelteKit 文档主题
• get_tailwind_info - 获取特定的 Tailwind CSS 信息
• list_sveltekit_topics - 列出可用的 SvelteKit 文档（有限）
• list_tailwind_info_topics - 列出 Tailwind 文档（有限）

组件工具

• get_component_snippet - 获取 Svelte 组件代码
• list_snippet_categories - 列出组件类别
• list_snippets_in_category - 列出类别中的片段

增强工具模式

所有工具包括：

• 模式验证，带有正则表达式约束
• 长度限制，用于输入参数
• 全面描述，带有使用示例
• 安全加固，输入清理

📝 使用示例

MCP 客户端配置

选项 1：Smithery 托管（推荐）

{
  "mcpServers": {
    "tailwind-svelte-assistant": {
      "url": "https://server.smithery.ai/@CaullenOmdahl/tailwind-svelte-assistant/mcp",
      "transport": "http"
    }
  }
}

选项 2：本地安装

{
  "mcpServers": {
    "tailwind-svelte-assistant": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {}
    }
  }
}

工具使用

推荐：完整文档

// 获取完整的 Svelte/SvelteKit 文档（1MB，100% 覆盖）
await client.callTool("get_svelte_full_docs", {});

// 获取完整的 Tailwind CSS 文档（2.1MB，100% 覆盖）
await client.callTool("get_tailwind_full_docs", {});

// 在 Svelte 文档中搜索
await client.callTool("search_svelte_docs", {
  query: "load 函数",
  limit: 5  // 可选
});

// 在 Tailwind 文档中搜索
await client.callTool("search_tailwind_docs", {
  query: "内边距实用类",
  limit: 3  // 可选
});

旧版：特定主题（有限覆盖）

// 获取特定的 SvelteKit 主题（仅覆盖约 8% 的文档）
await client.callTool("get_sveltekit_doc", { topic: "路由" });

// 获取特定的 Tailwind 信息（仅覆盖约 4% 的文档）
await client.callTool("get_tailwind_info", { query: "内边距" });

// 列出可用的主题（有限）
await client.callTool("list_tailwind_info_topics", {});

组件片段

// 获取一个组件片段
await client.callTool("get_component_snippet", {
  component_category: "页眉",
  snippet_name: "默认导航栏"
});

// 列出片段类别
await client.callTool("list_snippet_categories", {});

🧪 测试与质量保证

安全审计

npm run security-audit

依赖项检查

npm run outdated-check

MCP 检查器

npm run inspector

🐳 Docker 部署

包含的 Dockerfile 提供了一个安全的多阶段构建：

# 多阶段构建，带有安全加固
FROM node:18-alpine AS builder
# ... 构建过程

FROM node:18-alpine AS release
# ... 生产环境设置，使用非 root 用户

安全特性

• 多阶段构建 减少攻击面
• Alpine Linux 以最小化占用空间
• 非 root 用户 以提高容器安全性
• 仅生产依赖项

📈 监控与日志

结构化日志

所有操作都以结构化的 JSON 格式记录，便于解析：

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "level": "info",
  "operation": "tool_request",
  "tool": "get_sveltekit_doc",
  "topic": "路由"
}

审计事件

• 工具请求，带有参数
• 安全违规 和被阻止的请求
• 错误条件，带有分类
• 性能指标 和缓存命中

🔄 从 v0.1.0 迁移

破坏性变更

• ES 模块：更新为使用 import/export 而不是 require
• TypeScript：严格类型可能需要类型断言
• 错误消息：更安全，更少的详细错误消息

兼容性

• 工具接口：所有现有工具具有改进的验证
• 内容结构：内容组织没有变化
• Docker：更新了基础镜像和安全加固

🤝 贡献

开发指南

1. 安全第一：所有更改必须通过安全审查
2. 类型安全：保持严格的 TypeScript 合规性
3. 测试覆盖率：包含新功能的测试
4. 文档：更新 README 以反映任何 API 变更

代码审查清单

• 对所有用户输入进行输入验证
• 错误处理带有安全的错误消息
• TypeScript 类型不使用 any
• 路径操作的安全审计
• 性能影响评估

📚 文档

• MCP 规范
• 安全最佳实践
• TypeScript SDK

🐛 故障排除

常见问题

构建错误

# 清除 dist 并重新构建
rm -rf dist && npm run build

权限错误

# 确保可执行权限
chmod +x dist/index.js

导入错误

• 确保使用 Node.js 18+ 以支持 ES 模块
• 检查 package.json 中的 "type": "module"

安全问题

如果您发现安全漏洞，请通过带有 security 标签的 GitHub 问题报告。

📄 许可证

本项目遵循与原始 Tailwind-Svelte-Assistant 项目相同的许可证。

---

⚡ 性能基准

之前与之后 (v0.1.1)

• 文档覆盖：🔴 4-8% → 🟢 100%（12.5x-25x 改进）
• 安全性：🔴 严重漏洞 → 🟢 加固
• 类型安全：🟡 混合类型 → 🟢 严格 TypeScript
• 性能：🟡 无缓存 → 🟢 5 分钟 LRU 缓存
• 架构：🔴 单体 → 🟢 模块化服务
• 错误处理：🟡 基本 → 🟢 全面分类

文档指标

• Svelte/SvelteKit：1,065,921 字节（1.04 MB）
• Tailwind CSS：2,197,160 字节（2.1 MB，249 个文件）
• 总标记：606,587 标记（Tailwind）
• 更新方法：通过 npm 脚本自动化

缓存性能

• 冷启动：~50-100ms 每次文件读取
• 缓存命中：~1-5ms 响应时间
• 内存使用：~1-3MB 每个缓存的完整文档
• 缓存效率：典型使用情况下的 80-95% 命中率
• 搜索性能：<10ms 的内存搜索

文档来源

• Svelte：来自 Svelte 团队的官方 LLM 优化格式
• Tailwind：从官方 GitHub 仓库通过 Repomix 提取
• 更新：带有回退机制的自动化脚本

此升级的 MCP 服务器将原始原型转变为具有 完整文档覆盖、企业级安全、性能和可维护性的生产就绪服务。