DarkLens–暗模式检测MCP服务器
一个生产级的模型上下文协议（MCP）服务器，使AI代理能够检测、分类、解释和道德地重新设计网站和UI流中的暗模式。
概述
DarkLens分析UI元素、同意流、定价结构和交互摩擦，以识别操纵性设计模式。它提供适合推理和合规性评估的结构化JSON输出。
特性
- 模式检测：基于规则的+NLP启发式方法，用于识别9+个暗模式类别
- 分类：通过认知偏差分析和严重程度对模式进行分类
- 伦理解释：对操纵策略和潜在危害的简明英语解释
- 符合性评估：GDPR、FTC和DPDP法规下的风险评分
- 伦理替代方案：建议重新设计UI流程和复制
支持的深色图案
- 确认羞辱
- 强迫同意
- 蟑螂汽车旅馆
- 隐性成本
- 偷偷溜进篮子
- 虚假紧迫感
- 视觉操纵
- 默认偏差利用
- 唠叨/反复打断
- 社会证明操纵 （通过Kaggle数据集增强）
数据源
检测系统通过来自 Kaggle暗模式数据集，提供了2000多个标记的电子商务和网络界面中的暗模式示例。
安装
先决条件
- Python 3.10或更高版本
uv包管理器（推荐）或pip
使用紫外线进行安装（推荐）
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone or navigate to the project directory
cd /path/to/DarkLens-MCP-Server
# Install dependencies
uv sync使用pip安装
# Install dependencies
pip install -e .项目结构
DarkLens-MCP-Server/
├── darklens_mcp_server/
│ └── server.py # Main MCP server implementation
├── data/
│ └── dark_patterns.json # Pattern taxonomy database
├── demo/ # Example usage scripts
├── pyproject.toml # Project configuration
├── requirements.txt # Alternative dependencies
├── README.md # This file
└── uv.lock # Lock file for uv服务端组件
资源
dark_patterns://taxonomy：完整的深色图案分类ui_text://{url}：从网页中提取UI文本元素
工具
detect_dark_patterns：分析HTML/text/URL中的暗模式classify_pattern：获取模式的详细分类explain_manipulation：解释心理操纵risk_score：评估法律/合规风险suggest_ethical_alternative：获取道德重新设计建议
提示
audit_website：全面的网站审计模板explain_ui_to_user：面向非技术用户的UI说明compliance_report：用户体验道德合规报告模板rewrite_cta：道德CTA重写模板assess_gdpr_risk：GDPR风险评估模板
用法
运行MCP服务器
# With uv
uv run darklens_mcp_server
# With Python
python -m darklens_mcp_server.server服务器通过MCP协议的stdio进行通信。
MCP客户端集成
使用任何兼容MCP的客户端进行连接。
示例工具调用
{
"method": "tools/call",
"params": {
"name": "detect_dark_patterns",
"arguments": {
"input_type": "url",
"content": "https://example.com"
}
}
}示例响应
{
"result": [
{
"pattern_id": "confirmshaming",
"pattern_type": "Confirmshaming",
"confidence": 0.9,
"evidence": ["No thanks, I don't want to save money"]
}
]
}API 参考
detect_dark_patters
输入：
input_type：“html”|“text”|“url”content：要分析的字符串内容
输出： 带有ID、类型、置信度和证据的检测模式数组。
分类模式
输入： pattern_id：字符串 输出： 类别、认知偏差、严重程度。
解释操纵
输入： pattern_id：字符串， user_type：“儿童”|“老年人”|“普通用户” 输出： 简单解释，心理学原理，潜在危害。
风险_核心
输入： pattern_id：字符串， region：“欧盟”|“美国”|“印度” 输出： 风险评分（0-100），违反规定，执行可能性。
建议伦理替代方案
输入： pattern_id：字符串 输出： 重写UI副本，重新设计流程，道德论证。
伦理考量
该工具旨在促进合乎道德的用户体验设计和监管合规性。负责任地使用：
- 对网站进行操纵模式审计
- 对设计师进行道德替代品教育
- 确保遵守隐私和消费者保护法
- 提高用户信任度和体验
免责声明： 该工具基于既定的暗模式研究提供分析，但不应被视为法律建议。始终就合规事宜咨询法律专家。
贡献
欢迎投稿！请确保代码遵循既定的模式，并包含适当的测试。
许可证
资源
资源提供对数据的只读访问。它们类似于REST API中的GET端点。
静态资源
@mcp.resource("users://list")
def get_users_list() -> str:
"""Get a list of all users."""
return json.dumps(SAMPLE_USERS, indent=2)带参数的动态资源
@mcp.resource("users://{user_id}")
def get_user_by_id(user_id: str) -> str:
"""Get a specific user by ID."""
# Implementation...API外部资源
@mcp.resource("api://external/{endpoint}")
async def get_external_api_data(endpoint: str) -> str:
"""Fetch data from an external API endpoint."""
# Implementation...工具
工具是可以执行计算、API调用或其他操作的可执行函数。执行前可能需要用户批准。
同步工具
@mcp.tool()
def calculate_sum(numbers: List[float]) -> float:
"""Calculate the sum of a list of numbers."""
return sum(numbers)异步工具
@mcp.tool()
async def fetch_user_posts(user_id: int) -> str:
"""Fetch posts for a specific user from external API."""
async with httpx.AsyncClient() as client:
response = await client.get(f"{API_BASE_URL}/posts?userId={user_id}")
return json.dumps(response.json(), indent=2)具有复杂逻辑的工具
@mcp.tool()
def analyze_text(text: str) -> Dict[str, Any]:
"""Analyze text and return statistics."""
words = text.split()
return {
"word_count": len(words),
"character_count": len(text),
# ... more analysis
}提示
提示是可重用的模板，可帮助LLM与您的服务器有效交互。它们定义了预期的输入和交互模式。
简单提示
@mcp.prompt()
def summarize_content(content: str, max_length: int = 100) -> str:
"""Create a prompt to summarize content."""
return f"Please summarize the following content in {max_length} words or less:\n\n{content}"复杂提示
@mcp.prompt()
def create_study_plan(subject: str, hours_per_week: int, weeks: int) -> str:
"""Create a study plan prompt."""
return f"""Create a detailed study plan for learning {subject}.
Available time: {hours_per_week} hours per week
Duration: {weeks} weeks
Please include:
1. Weekly breakdown of topics
2. Daily study schedule
3. Recommended resources
4. Assessment milestones
5. Tips for effective learning"""运行服务器
使用紫外线
uv run darklens-server直接使用Python
python -m darklens_mcp_server.server使用脚本
darklens-server服务器将启动并通过stdio监听MCP协议消息。
测试服务器
使用MCP检查器
测试MCP服务器的最简单方法是使用MCP检查器：
# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector
# Run the inspector with your server
mcp-inspector uv run darklens-server这将打开一个web界面，您可以在其中与服务器的资源、工具和提示进行交互。
与客户进行手动测试
您还可以创建一个简单的测试客户端：
import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client
async def test_server():
async with stdio_client(
StdioServerParameters(command="uv", args=["run", "darklens-server"])
) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# List resources
resources = await session.list_resources()
print("Available resources:", [r.uri for r in resources.resources])
# List tools
tools = await session.list_tools()
print("Available tools:", [t.name for t in tools.tools])
# List prompts
prompts = await session.list_prompts()
print("Available prompts:", [p.name for p in prompts.prompts])
# Test a resource
resource_content = await session.read_resource("users://list")
print("Users resource content:", resource_content.contents[0].text)
# Test a tool
result = await session.call_tool("calculate_sum", {"numbers": [1, 2, 3, 4, 5]})
print("Sum tool result:", result.content[0].text)
# Test a prompt
prompt_result = await session.get_prompt("summarize_content", {
"content": "This is a sample text to summarize.",
"max_length": 50
})
print("Prompt result:", prompt_result.messages[0].content)
asyncio.run(test_server())与Claude Desktop集成
要将此服务器与Claude Desktop一起使用，请执行以下操作：
- 配置Claude桌面:
- 打开 ~/Library/Application Support/Claude/claude_desktop_config.json - 添加您的服务器配置：
{
"mcpServers": {
"darklens": {
"command": "uv",
"args": [
"--directory",
"/path/to/DarkLens-MCP-Server",
"run",
"darklens-server"
]
}
}
}- 重新启动克劳德桌面
- 克劳德测试:
- 让Claude“列出可用资源”或“使用calculate_sum工具” - 尝试以下提示：“制定一个学习Python的学习计划，每周10小时，持续8周”
可用资源
users://list-列出所有示例用户users://{user_id}-按ID获取特定用户posts://list-列出所有示例帖子api://external/{endpoint}-从JSONPlaceholder API获取数据
可用工具
calculate_sum-将一系列数字相加find_max-在列表中查找最大值reverse_string-反转字符串fetch_user_posts-从外部API获取用户的帖子analyze_text-分析文本统计信息
可用提示
summarize_content-创建摘要提示analyze_sentiment-创建情绪分析提示generate_code-创建代码生成提示create_study_plan-创建学习计划提示
最佳实践
资源
- 保持资源函数的轻量级-避免繁重的计算
- 为不同的内容类型使用适当的MIME类型
- 优雅地处理错误并返回有意义的错误消息
- 为动态资源使用URI模板
工具
- 包含带有参数描述的清晰文档字符串
- 验证输入参数
- 妥善处理错误
- 对I/O操作使用异步函数
- 保持工具名称的描述性和一致性
提示
- 使用可选参数使提示灵活
- 包括LLM的明确说明
- 结构提示输出一致
- 使用描述性名称和描述
将军
- 使用日志记录而不是打印语句（MCP使用stdio进行通信）
- 部署前彻底测试服务器
- 处理边缘情况和无效输入
- 遵循Python类型提示以获得更好的工具支持
故障排除
服务器无法启动
- 检查Python版本（必须是3.10+）
- 验证是否已安装所有依赖项
- 检查代码中的语法错误
工具/资源未显示
- 确保正确使用装饰剂(
@mcp.tool()，不@mcp.tool) - 检查函数是否有正确的类型提示
- 验证服务器初始化
Claude桌面集成问题
- 在配置文件中检查服务器的路径
- 确保服务器启动时没有错误
- 配置更改后重新启动Claude Desktop
- 检查Claude Desktop日志是否有错误
常见错误
- “print（）中断MCP”：切勿使用
print()在生产环境中，它破坏了JSON-RPC协议 - “需要异步函数”：使用
async def用于执行I/O的功能 - “URI无效”：确保资源URI遵循正确的格式
下一步
- 探索 MCP文件 高级功能
- 看看 Python SDK示例
- 了解 构建MCP客户端
- 发现 其他MCP服务器
许可证
这个项目是作为一个教育例子提供的。您可以根据自己的MCP服务器实现自由修改和扩展它。