IMPROVEMENTS.md•8.04 kB
# Mermaid Chart MCP Server 改进总结
本文档总结了根据代码工程建议所做的全面改进。推荐使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 进行调试和测试。
## 🏗️ 架构改进
### 1. 目录结构重构
**之前:**
```
src/
├── server.ts
└── simple-mcp-server.ts
```
**之后:**
```
src/
├── server/
│ ├── index.ts # 主入口文件
│ ├── simple-mcp-server.ts # MCP服务器核心逻辑
│ ├── sse-transport.ts # SSE传输和Web服务器
│ └── utils.ts # 工具函数（校验、清理等）
├── package.json
├── tsconfig.json
├── tsup.config.ts # 构建配置
└── README.md
```
**改进效果:**
- ✅ 模块化设计，职责分离
- ✅ 更好的可维护性
- ✅ 清晰的依赖关系
### 2. 构建系统优化
**新增 tsup 配置:**
```typescript
// tsup.config.ts
export default defineConfig({
entry: {
'server/index': 'src/server/index.ts',
// ... 其他入口
},
format: ['esm'],
target: 'node18',
sourcemap: true,
dts: true,
banner: {
js: '#!/usr/bin/env node'
}
});
```
**改进效果:**
- ✅ 快速的 ESM 构建
- ✅ 自动生成类型声明文件
- ✅ 源码映射支持
- ✅ 正确的 shebang 处理
## 🛡️ 安全性改进
### 1. ESM 环境全局污染解决
**之前的问题:**
```typescript
// 直接修改全局变量，多用户并发时有竞态问题
global.window = window;
global.document = window.document;
```
**改进后:**
```typescript
// 创建隔离的渲染环境
private async renderMermaidInIsolatedContext(mermaidCode: string, theme: string): Promise<string> {
const dom = new JSDOM('<!DOCTYPE html>...');
const originalWindow = global.window;
const originalDocument = global.document;
try {
global.window = dom.window;
global.document = dom.window.document;
// 渲染逻辑...
} finally {
// 恢复原始全局变量
if (originalWindow !== undefined) {
global.window = originalWindow;
} else {
delete (global as any).window;
}
dom.window.close();
}
}
```
**改进效果:**
- ✅ 避免全局污染
- ✅ 多用户并发安全
- ✅ 资源自动清理
### 2. 输入校验和安全性
**新增校验函数:**
```typescript
export function validateInput(params: {
mermaidCode?: string;
title?: string;
theme?: string;
}): string | null {
// 长度限制
if (mermaidCode && mermaidCode.length > 50000) {
return 'mermaidCode 长度不能超过50000字符';
}
// 恶意内容检测
if (/<script|javascript:|data:|vbscript:/i.test(mermaidCode)) {
return 'mermaidCode 包含不安全的内容';
}
// 特殊字符过滤
if (title && /<|>|&|"|'|`/.test(title)) {
return 'title 包含不允许的特殊字符';
}
}
```
**改进效果:**
- ✅ 防止恶意输入
- ✅ XSS 防护
- ✅ 文件名安全化
## 🎨 功能改进
### 1. 稳健的 SVG 标题添加
**之前的问题:**
```typescript
// 简单字符串替换，可能有边缘 bug
return svg.replace('<svg', `<svg${titleElement ? '\n ' + titleElement : ''}`);
```
**改进后:**
```typescript
private addTitleToSVG(svg: string, title: string): string {
try {
// 使用 DOM 解析器插入 title 元素
const dom = new JSDOM(`<!DOCTYPE html><html><body>${svg}</body></html>`);
const svgElement = dom.window.document.querySelector('svg');
if (svgElement) {
const titleElement = dom.window.document.createElement('title');
titleElement.textContent = title;
svgElement.insertBefore(titleElement, svgElement.firstChild);
return svgElement.outerHTML;
}
// 回退方案...
} catch (error) {
// 回退到字符串替换
}
}
```
**改进效果:**
- ✅ 更稳健的 DOM 操作
- ✅ 优雅的错误回退
- ✅ 避免格式问题
### 2. 精细的图表类型检测
**改进后:**
```typescript
private detectDiagramType(mermaidCode: string): string {
const patterns = [
{ pattern: /^(graph|flowchart)\s+(TD|TB|BT|RL|LR)/, type: '流程图' },
{ pattern: /^sequencediagram/m, type: '序列图' },
{ pattern: /^classDiagram/m, type: '类图' },
{ pattern: /^statediagram(-v2)?/m, type: '状态图' },
// ... 更多精确匹配
];
for (const { pattern, type } of patterns) {
if (pattern.test(code)) {
return type;
}
}
}
```
**改进效果:**
- ✅ 更精确的类型识别
- ✅ 支持更多图表类型
- ✅ 正则表达式优化
## 🌐 Web 服务改进
### 1. CORS 和安全配置
**新增功能:**
```typescript
private setupCORS(app: express.Application): void {
app.use((req, res, next) => {
const allowedOrigins = process.env.ALLOWED_ORIGINS
? process.env.ALLOWED_ORIGINS.split(',')
: ['*'];
const origin = req.headers.origin;
if (allowedOrigins.includes('*') || (origin && allowedOrigins.includes(origin))) {
res.header('Access-Control-Allow-Origin', origin || '*');
}
// ... 其他 CORS 配置
});
}
```
**改进效果:**
- ✅ 灵活的 CORS 配置
- ✅ 生产环境域名白名单
- ✅ 安全性提升
### 2. SSE 连接管理
**新增功能:**
```typescript
export class SSETransport {
private activeConnections = new Set<SSEServerTransport>();
async start(port: number): Promise<void> {
// 连接管理
res.on('close', () => {
this.activeConnections.delete(transport);
});
// 优雅关闭
process.on('SIGTERM', () => {
this.cleanup();
server.close();
});
}
private cleanup(): void {
for (const connection of this.activeConnections) {
this.activeConnections.delete(connection);
}
}
}
```
**改进效果:**
- ✅ 自动连接清理
- ✅ 资源释放管理
- ✅ 优雅关闭处理
### 3. 现代化测试界面
**新增功能:**
- 🎨 Material Design 风格 UI
- 📱 响应式设计
- 🧪 实时代码测试
- 📊 服务器状态监控
- 🔗 API 端点信息
## 📦 工程实践改进
### 1. package.json 优化
**新增配置:**
```json
{
"main": "dist/server/index.js",
"types": "dist/server/index.d.ts",
"bin": {
"mermaid-mcp": "./dist/server/index.js"
},
"exports": {
"import": "./dist/server/index.js",
"types": "./dist/server/index.d.ts"
},
"scripts": {
"build": "tsup",
"start:dev": "node --loader ts-node/esm src/server/index.ts",
"clean": "rm -rf dist",
"prepublishOnly": "npm run clean && npm run build"
}
}
```
**改进效果:**
- ✅ 正确的 ESM 导出
- ✅ bin 脚本支持
- ✅ 开发和生产分离
### 2. TypeScript 严格配置
**保持严格模式:**
```json
{
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noImplicitReturns": true
}
```
**改进效果:**
- ✅ 类型安全
- ✅ 代码质量保证
- ✅ 潜在错误预防
## 📈 性能优化
### 1. 内存管理
- ✅ JSDOM 实例自动清理
- ✅ 连接池管理
- ✅ 临时文件清理
### 2. 并发性能
- ✅ 隔离渲染环境
- ✅ 非阻塞异步处理
- ✅ 连接状态监控
## 🚀 部署改进
### 1. 构建优化
- ✅ 快速 ESM 构建
- ✅ 源码映射支持
- ✅ Tree-shaking 优化
### 2. 运行时优化
- ✅ 正确的 shebang 处理
- ✅ 进程信号处理
- ✅ 环境变量配置
## 📚 文档完善
### 1. 用户文档
- ✅ 详细的 README
- ✅ API 文档
- ✅ 部署指南
### 2. 开发文档
- ✅ 变更日志
- ✅ 改进总结
- ✅ 环境变量示例
## 🎯 总结
这次改进涵盖了代码工程的各个方面：
1. **架构设计**: 模块化、职责分离
2. **安全性**: 输入校验、全局污染解决
3. **性能**: 内存管理、并发优化
4. **工程实践**: 构建优化、文档完善
5. **用户体验**: 现代化界面、错误处理
所有改进都遵循了现代 TypeScript/Node.js 项目的最佳实践，确保了代码的可维护性、安全性和性能。