leanix design MCP server

LeanIX设计代理MCP服务器

一个智能MCP服务器，从LeanIX公开基于AI的设计标准查询。使用FastMCP、LangGraph和OpenAI构建。

🎯 这是什么？

此MCP（模型上下文协议）服务器充当 智能网关 AI助手和LeanIX之间。它使用人工智能来理解自然语言查询，并自动编排多个LeanIX工具来获取设计标准、架构模式和最佳实践。

它解决的问题

如果没有此服务器：

• 人工智能助理需要了解50多种LeanIX工具
• 需要复杂的手动工具选择
• 原始、未格式化的数据响应
• 需要深厚的LeanIX专业知识

使用此服务器：

• 4个简单、专注的工具
• AI自动选择合适的LeanIX工具
• 连贯、综合的答案
• 自然语言查询

🏗️ 建筑

┌─────────────────────────────────┐
│  AI Assistant (MCP Client)      │
│  GitHub Copilot / Claude /      │
│  Cursor / Any MCP Client        │
└────────────┬────────────────────┘
             │ HTTP (MCP Protocol)
             ▼
┌─────────────────────────────────┐
│  Your MCP Server (port 8000)    │
│  ┌───────────────────────────┐  │
│  │  FastMCP Framework        │  │
│  │  4 Intelligent Tools      │  │
│  └───────────┬───────────────┘  │
│              │                   │
│              ▼                   │
│  ┌───────────────────────────┐  │
│  │  AI Agent                 │  │
│  │  - OpenAI GPT             │  │
│  │  - LangGraph ReAct        │  │
│  │  - Query Understanding    │  │
│  │  - Tool Orchestration     │  │
│  └───────────┬───────────────┘  │
└──────────────┼──────────────────┘
               │ HTTP (MCP Protocol)
               ▼
┌─────────────────────────────────┐
│  LeanIX MCP Server              │
│  50+ Low-Level Tools            │
│  (search, get, list, etc.)      │
└─────────────────────────────────┘

价值主张

🚀 快速开始

先决条件

• Python 3.10+
• OpenAI API密钥
• 通过身份验证访问LeanIX MCP服务器

1.安装

# Clone or download this project
cd leanix_design_agent

# Install dependencies
pip install -r requirements.txt

2.配置

创建一个 .env 项目根目录中的文件：

# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_MODEL=gpt-4o-mini

# LeanIX MCP Server (connects TO LeanIX)
LEANIX_MCP_URL=https://your-leanix-mcp-server.com/mcp
LEANIX_MCP_AUTH_BEARER=your_leanix_bearer_token_here
LEANIX_MCP_TRANSPORT=streamable_http
LEANIX_MCP_SERVER_NAME=leanix

# Your MCP Server Configuration
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8000

3.运行服务器

选项A：使用run.py（推荐）

python run.py

选项B：直接执行

python src/server.py

选项C：自动重新加载的开发模式

fastmcp dev src/server.py

服务器将在以下时间启动： http://localhost:8000

4.验证服务器是否正在运行

# Check server health
curl http://localhost:8000

# Should return MCP server info

🛠️ 可用工具

服务器公开了MCP客户端可以使用的4个智能工具：

1. search_design_standards

搜索设计标准、最佳实践和架构指南。

参数：

• topic （string）：要搜索的主题

示例：

• “事件驱动架构”
• “微服务最佳实践”
• “API设计指南”
• “云部署标准”

2. get_architecture_patterns

获取特定架构风格的架构模式和设计指南。

参数：

• architecture_type （string）：架构类型

示例：

• “微服务”
• “事件驱动”
• “无服务器”
• “整体”
• “SOA”

3. get_technology_standards

获取特定技术或框架的技术标准和指南。

参数：

• technology （string）：技术名称

示例：

• “卡夫卡”
• “库贝内特斯”
• “反应”
• “PostgreSQL”
• “Docker”

4. get_security_guidelines

获取安全指南、最佳实践和标准。

参数：

• security_area （string）：安全区域

示例：

• “API安全性”
• “身份验证”
• “数据加密”
• “网络安全”
• “OAuth实现”

🔌 连接MCP客户端

通用MCP客户端配置

{
  "servers": {
    "leanix-design-agent": {
      "url": "http://localhost:8000",
      "transport": "streamable_http"
    }
  }
}

示例：Python客户端

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient

async def query_leanix():
    connections = {
        "leanix-design": {
            "transport": "streamable_http",
            "url": "http://localhost:8000"
        }
    }
    
    async with MultiServerMCPClient(connections) as client:
        tools = await client.get_tools()
        print(f"Available tools: {[t.name for t in tools]}")
        
        # Call a tool
        result = await client.call_tool(
            "search_design_standards",
            {"topic": "microservices"}
        )
        print(result)

asyncio.run(query_leanix())

示例：使用FastMCP客户端

from fastmcp import FastMCP

# Connect to your server
client = FastMCP("http://localhost:8000")

# Call a tool
result = await client.call_tool(
    "get_architecture_patterns",
    {"architecture_type": "event-driven"}
)
print(result)

📁 项目结构

leanix_design_agent/
│
├── src/
│   ├── __init__.py           # Package marker
│   ├── server.py             # Main MCP server (consolidated)
│   │   ├── LeanIX client     #   - Connect to LeanIX MCP
│   │   ├── AI agent          #   - Build intelligent agent
│   │   ├── MCP tools (x4)    #   - Tool definitions
│   │   └── Main entry        #   - Server startup
│   └── config.py             # Configuration management
│
├── run.py                    # Entry point script
├── requirements.txt          # Python dependencies
├── .env                      # Environment variables (create this)
├── .env.example              # Environment template
├── .gitignore               # Git ignore rules
└── README.md                # This file

文件描述

src/server.py （208行）-主服务器文件包含：

• LeanIX客户端：连接管理、工具检索、过滤
• AI 代理：带有OpenAI的LangGraph ReAct代理用于智能查询
• MCP工具：4 FastMCP工具定义
• 服务器：FastMCP HTTP服务器设置

src/config.py -具有验证的配置类：

• OpenAIConfig：API键，型号选择
• LeanIXMCPConfig：LeanIX服务器连接详细信息

run.py -导入和运行服务器的简单入口点

⚙️ 配置参考

环境变量

OpenAI模型选项

# Most cost-effective (recommended)
OPENAI_MODEL=gpt-4o-mini

# More capable, higher cost
OPENAI_MODEL=gpt-4o

# Turbo models
OPENAI_MODEL=gpt-4-turbo
OPENAI_MODEL=gpt-3.5-turbo

🔍 运作原理

请求流

1. MCP客户端 发送工具请求：

   {
     "tool": "search_design_standards",
     "arguments": {"topic": "microservices"}
   }

1. FastMCP 通往适当工具功能的路线

1. AI 代理:

- 连接到LeanIX MCP服务器 - 检索可用的LeanIX工具（50多种工具） - 相关工具的过滤器（搜索、查找、获取、概况介绍） - 使用OpenAI创建LangGraph ReAct代理

1. 重新代理 （推理+表演）：

- 原因：“用户想要微服务设计标准” - 行为：调用适当的LeanIX工具 - 观察：查看结果 - 重复：如果需要更多信息 - 合成：创建连贯的最终答案

1. 响应 以格式化文本的形式返回给MCP客户端

示例：幕后

用户查询： “获取微服务最佳实践”

发生了什么：

1. Your MCP Server receives: get_architecture_patterns("microservices")

2. AI Agent thinks:
   "I need to search LeanIX for microservices patterns"
   
3. AI Agent discovers LeanIX has these tools:
   - search_fact_sheets
   - search_documents  
   - get_technology_stack
   - list_design_patterns
   [... 46 more tools]
   
4. AI Agent filters to relevant tools:
   - search_fact_sheets ✅
   - search_documents ✅
   - get_overview ✅
   
5. AI Agent automatically:
   - Calls search_fact_sheets(type="architecture", name="microservices")
   - Calls search_documents(query="microservices patterns")
   - Combines results
   
6. AI Agent synthesizes:
   "Microservices Best Practices from LeanIX:
    1. Service independence...
    2. API-first design...
    3. Decentralized data..."
    
7. Returns formatted response ✅

🧪 发展

以开发模式运行

# Auto-reload on file changes
fastmcp dev src/server.py

手动测试工具

# test_manual.py
import asyncio
from src.server import _query_leanix

async def test():
    result = await _query_leanix("Get microservices patterns")
    print(result)

asyncio.run(test())

调试

启用调试日志记录：

# In src/server.py, change:
logging.basicConfig(level=logging.DEBUG)  # Instead of INFO

🐛 故障排除

服务器无法启动

错误：“未设置OPENAI_API_KEY”

• ✅ 创建 .env 项目根目录中的文件
• ✅ 添加 OPENAI_API_KEY=sk-...
• ✅ 验证 .env 与位于同一目录中 run.py

错误：“必须设置LEANIX_MCP_URL”

• ✅ 添加 LEANIX_MCP_URL=https://... 到 .env
• ✅ 验证URL是否正确且可访问
• ✅ 检查LeanIX MCP服务器是否正在运行

错误：端口8000已在使用中

# Change port in .env
MCP_SERVER_PORT=8001

连接问题

无法连接到LeanIX MCP

• ✅ 验证 LEANIX_MCP_URL 是正确的
• ✅ 支票持有人令牌尚未过期
• ✅ 手动测试URL： curl
• ✅ 验证网络/防火墙是否允许连接

未从LeanIX中找到工具

• ✅ 检查身份验证令牌权限
• ✅ 查看LeanIX MCP服务器日志
• ✅ 验证传输类型是否匹配： streamable_http

查询问题

反应缓慢

• ⚠️ 正常：第一次查询需要更长的时间（代理初始化）
• ⚠️ LeanIX的响应时间可能较慢
• ⚠️ 复杂的查询需要多个工具调用
• ✅ 考虑使用更快的OpenAI模型

答案质量差

• ✅ 尝试不同的OpenAI模型： OPENAI_MODEL=gpt-4o
• ✅ 检查LeanIX是否有相关数据
• ✅ 重新表述查询以使其更具体

OpenAI速率限制

• ✅ 验证API密钥是否具有信用
• ✅ 检查OpenAI仪表板的限制
• ✅ 考虑升级OpenAI计划

📊 演出

典型响应时间

优化提示

1. 使用 gpt-4o-mini -更快更便宜
2. 保持查询的具体性 -减少所需的工具调用
3. 考虑缓存 -为重复查询添加缓存层
4. 连接池 -LeanIX客户端重用连接

📦 依赖项

fastmcp              # MCP server framework
langgraph            # Agent orchestration
langchain            # LLM application framework
langchain-openai     # OpenAI integration
langchain-mcp-adapters  # MCP client support
python-dotenv        # Environment management

依赖关系树

Your MCP Server
├── fastmcp           → MCP server capabilities
├── langgraph         → AI agent orchestration
│   └── langchain     → LLM framework
│       └── langchain-openai  → OpenAI GPT
└── langchain-mcp-adapters    → Connect to LeanIX MCP

🔒 安全考虑

• ⚠️ 永不承诺 .env -包含API密钥和令牌
• 🔒 定期旋转令牌 -不记名代币应该过期
• 🛡️ 在生产环境中使用HTTPS -加密流量
• 📝 审计查询 -记录所询问的内容
• 🔐 限制网络访问 -服务器防火墙规则
• 💰 监控OpenAI使用情况 -设定预算限额

🚀 生产部署

Docker部署（推荐）

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY src/ ./src/
COPY run.py .

EXPOSE 8000
CMD ["python", "run.py"]

# Build
docker build -t leanix-design-agent .

# Run
docker run -p 8000:8000 --env-file .env leanix-design-agent

环境特定配置

# Development
.env.development

# Staging
.env.staging

# Production
.env.production

健康检查

添加健康端点监控：

curl http://localhost:8000/health

🤝 贡献

这是一个内部工具。如需修改：

1. 本地测试： fastmcp dev src/server.py
2. 与MCP客户端进行验证
3. 如果添加功能，请更新README
4. 确保 .env 在...里 .gitignore

📄 许可证

\[指定您的许可证\]

🆘 支持

• OpenAI问题: https://platform.openai.com/docs
• LeanIX支持：请联系您的LeanIX管理员
• FastMCP文档: https://github.com/jlowin/fastmcp

______________________________________________________________________

🎓 了解MCP架构

为什么使用MCP？

MCP（模型上下文协议） 是用于将AI助手连接到外部工具和数据源的标准化协议。

优点：

• ✅ 标准化：适用于任何兼容MCP的客户端
• ✅ 工具发现：客户端自动学习可用工具
• ✅ 类型安全：基于模式的参数验证
• ✅ AI Native：专为AI到AI通信而设计

服务器的角色

您的服务器是 中间件/外观 即：

1. 抽象复杂性：4个简单的工具，而不是50多个复杂的工具
2. 增加智能：AI理解并协调查询
3. 综合结果：连贯的答案而不是原始数据
4. 领域焦点：专门用于设计标准

这是一个 最佳实践模式 在AI架构中！ 🎯

______________________________________________________________________

内置于❤️ 使用FastMCP、LangGraph和OpenAI