Tailwind Svelte Assistant MCP Server

Tailwind Svelte Assistant MCP 服务

一个安全、高性能的模型上下文协议（MCP）服务，提供完整的 SvelteKit 和 Tailwind CSS 文档（覆盖率 100%）与代码片段，并具备增强的安全性、规范的 TypeScript 实现和全面的错误处理。

✨ 新功能（v0.1.1）

📚 完整的文档覆盖

• 100% Svelte/SvelteKit 覆盖率：官方针对大模型优化的文档（1.04 MB）
• 100% Tailwind CSS 覆盖率：通过 Repomix 提取的完整文档（2.1 MB，249 个文件）
• 智能搜索：在完整文档中搜索并获取上下文
• 提升 12.5 至 25 倍：覆盖率从 4% 至 8% 提升到 100%

🚀 主要改进（v0.1.1）

🔒 安全性增强

• 路径遍历防护：全面的输入清理可防止目录遍历攻击
• 输入验证：通过模式匹配和长度限制严格验证参数
• 安全的文件操作：通过路径验证和大小限制约束文件访问
• 审计日志：记录结构化安全事件，以便监控

🏗️ 架构改进

• 模块化设计：将各项职责拆分到专用服务和实用工具中
• 卓越的 TypeScript 实现：通过规范的接口实现完整类型安全，不使用 any 类型
• ES 模块：采用规范导入方式的现代 JavaScript 模块系统
• 错误处理：全面分类错误并安全地传达错误信息

⚡ 性能优化

• 内容缓存：采用可配置超时的 LRU 缓存，提升响应速度
• 文件大小限制：通过可配置限制防止资源耗尽
• 异步操作：使用非阻塞文件操作，提升并发能力
• 内存管理：自动清理缓存并进行垃圾回收

📁 项目结构

src/
├── index.ts                 # Main server with security hardening
├── types.ts                 # TypeScript type definitions
├── services/
│   └── fileService.ts       # Secure file operations with caching
└── utils/
    ├── security.ts          # Input validation and path sanitization
    └── errorHandler.ts      # Comprehensive error handling

🚀 快速开始

通过 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 max file size (for full docs)
  cacheTimeout: 5 * 60 * 1000,     // 5 minutes cache timeout
  contentBasePath: './content',
  svelteFullDocsPath: './content/docs/svelte-sveltekit-full.txt',
  tailwindFullDocsPath: './content/docs/tailwind-docs-full.txt',
  // ... other paths
};

文档更新

文档会自动下载和更新：

# Update all documentation (Svelte + Tailwind)
npm run update-content

此脚本将：

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

来源：

• Svelte/SvelteKit：官方针对大模型优化的文本文件（覆盖率 100%）
• Tailwind CSS：通过 Repomix 从 GitHub 代码仓库提取（249 个 MDX 文件）
• 代码片段：本地精选的组件示例（43 个文件）

🛡️ 安全功能

输入验证

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

错误处理

• 安全错误消息：不会向客户端泄露敏感信息
• 结构化日志记录：采用 JSON 格式的审计日志进行安全监控
• 错误分类：针对不同错误类型采取不同的处理方式
• 优雅降级：为非关键故障提供回退响应

文件系统安全

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

📊 性能特性

缓存系统

// Automatic content caching with configurable timeout
const fileService = new SecureFileService(
  1024 * 1024,    // Max file size
  5 * 60 * 1000   // Cache timeout (5 minutes)
);

资源管理

• 内存限制：文件大小限制可防止内存耗尽
• 缓存清理：自动移除过期的缓存条目
• 异步 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": {}
    }
  }
}

工具用法

推荐：完整文档

// Get complete Svelte/SvelteKit documentation (1MB, 100% coverage)
await client.callTool("get_svelte_full_docs", {});

// Get complete Tailwind CSS documentation (2.1MB, 100% coverage)
await client.callTool("get_tailwind_full_docs", {});

// Search within Svelte documentation
await client.callTool("search_svelte_docs", {
  query: "load function",
  limit: 5  // optional
});

// Search within Tailwind documentation
await client.callTool("search_tailwind_docs", {
  query: "padding utilities",
  limit: 3  // optional
});

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

// Get specific SvelteKit topic (only covers ~8% of docs)
await client.callTool("get_sveltekit_doc", { topic: "routing" });

// Get specific Tailwind info (only covers ~4% of docs)
await client.callTool("get_tailwind_info", { query: "padding" });

// List available topics (limited)
await client.callTool("list_tailwind_info_topics", {});

组件代码片段

// Get a component snippet
await client.callTool("get_component_snippet", {
  component_category: "headers",
  snippet_name: "navbar-default"
});

// List snippet categories
await client.callTool("list_snippet_categories", {});

🧪 测试与质量保证

安全审计

npm run security-audit

依赖项检查

npm run outdated-check

MCP Inspector

npm run inspector

🐳 Docker 部署

随附的 Dockerfile 提供了安全的多阶段构建：

# Multi-stage build with security hardening
FROM node:18-alpine AS builder
# ... build process

FROM node:18-alpine AS release
# ... production setup with non-root user

安全特性

• 多阶段构建可缩小攻击面
• Alpine Linux 占用空间小
• 非 root 用户可增强容器安全性
• 仅包含生产环境依赖项

📈 监控与日志记录

结构化日志记录

所有操作均使用结构化 JSON 格式记录，便于解析：

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

审计事件

• 工具请求及其参数
• 安全违规和已拦截的请求
• 错误情况及其分类
• 性能指标和缓存命中

🔄 从 v0.1.0 迁移

重大变更

• ES Modules：改为使用 import/export，而非 require
• TypeScript：严格类型检查在某些情况下可能需要类型断言
• 错误消息：更安全，且细节更少

兼容性

• 工具接口：所有现有工具均可正常使用，并获得更完善的验证
• 内容结构：内容组织方式没有变化
• Docker：更新了基础镜像并强化了安全性

🤝 贡献

开发指南

1. 安全优先：所有更改都必须通过安全审查
2. 类型安全：保持严格的 TypeScript 合规性
3. 测试覆盖率：为新功能添加测试
4. 文档：API 有任何变更时都要更新 README

代码审查清单

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

📚 文档

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

🐛 故障排除

常见问题

构建错误

# Clear dist and rebuild
rm -rf dist && npm run build

权限错误

# Ensure executable permissions
chmod +x dist/index.js

导入错误

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

安全问题

如果发现安全漏洞，请通过 GitHub issues 提交报告，并添加 security 标签。

📄 许可证

本项目沿用原始 Tailwind-Svelte-Assistant 项目的许可证。

---

⚡ 性能基准

更新前与更新后（v0.1.1）

• 文档覆盖率：🔴 4-8% → 🟢 100%（提升 12.5 倍至 25 倍）
• 安全性：🔴 严重漏洞 → 🟢 安全性加固
• 类型安全：🟡 混合类型 → 🟢 严格 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：通过 Repomix 从官方 GitHub 仓库提取
• 更新：带有回退机制的自动化脚本

这个升级后的 MCP 服务将原始原型改造为可用于生产环境的服务，具备完整的文档覆盖率、企业级安全性、高性能和易维护性。