Brand Nexus

BrandNexus

智能MCP服务器，通过Claude Desktop、Cursor IDE和VS Code将您的战略文档、品牌指南和消息模板无缝连接到AI驱动的工作流。

BrandNexus 通过在文档和人工智能助手之间创建智能桥梁，实现即时搜索、自动分类和组织知识的上下文访问，改变了组织管理和访问战略内容的方式。

______________________________________________________________________

🚀 快速开始

让BrandNexus在5分钟内运行：

# 1. Clone and setup
git clone [https://github.com/JackSmack1971/brand-nexus.git]
cd brand-nexus

# 2. Run automated deployment
chmod +x deploy_mcp_server.sh
./deploy_mcp_server.sh

# 3. Configure your AI client (Claude Desktop example)
# Edit ~/.config/claude-desktop/claude_desktop_config.json

立即开始使用：

• “索引所有战略文件”
• “搜索有关徽标使用的品牌指南”
• “查找产品发布的消息模板”

______________________________________________________________________

📋 目录

• 🏗️ 建筑
• ✨ 特性
• ⚡ 安装
• ⚙️ 配置
• 🎯 用法
• 🔌 客户端集成
• 📚 api参考
• 🔬 发展
• 🚀 高级功能
• 🛠️ 故障排除
• 🤝 贡献

______________________________________________________________________

🏗️ 建筑

BrandNexus使用模型上下文协议（MCP）实现了分层架构，以实现无缝的AI集成：

flowchart TB
    subgraph "Client Layer"
        A1[Cursor IDE]
        A2[Claude Desktop]
        A3[VS Code]
        A4[Custom MCP Clients]
    end
    
    subgraph "MCP Protocol"
        B1[stdio]
        B2[SSE Events]
        B3[HTTP Transport]
    end
    
    subgraph "FastMCP Server"
        C1[Tools API]
        C2[Resources API]
        C3[Document Search]
        C4[Content Retrieval]
        C5[Analysis Tools]
    end
    
    subgraph "Document Processing"
        D1[DocumentIndexer]
        D2[Classification Engine]
        D3[Metadata Extractor]
        D4[Content Parser]
        D5[Tag Processor]
    end
    
    subgraph "Storage Layer"
        E1[SQLite Database]
        E2[Full-text Index]
        E3[Metadata Tables]
        E4[Document Cache]
    end
    
    subgraph "File System"
        F1[/strategy/]
        F2[/brand/]
        F3[/messaging/]
        F4[/templates/]
        F5[/guidelines/]
    end
    
    A1 & A2 & A3 & A4 --> B1 & B2 & B3
    B1 & B2 & B3 --> C1 & C2 & C3 & C4 & C5
    C1 & C2 & C3 & C4 & C5 --> D1 & D2 & D3 & D4 & D5
    D1 & D2 & D3 & D4 & D5 --> E1 & E2 & E3 & E4
    F1 & F2 & F3 & F4 & F5 --> D4
    
    style A1 fill:#e1f5fe
    style A2 fill:#e1f5fe
    style A3 fill:#e1f5fe
    style A4 fill:#e1f5fe
    style C1 fill:#e8f5e8
    style C2 fill:#e8f5e8
    style E1 fill:#fff3e0
    style E2 fill:#fff3e0

文档处理工作流

sequenceDiagram
    participant Client as AI Client
    participant MCP as MCP Protocol
    participant Server as FastMCP Server
    participant Indexer as Document Indexer
    participant DB as SQLite Database
    participant FS as File System
    
    Note over Client,FS: Document Indexing Flow
    Client->>MCP: "Index all documents"
    MCP->>Server: index_documents()
    Server->>FS: Scan directories
    FS-->>Server: File list
    Server->>Indexer: Process files
    Indexer->>DB: Store metadata & content
    DB-->>Indexer: Confirmation
    Indexer-->>Server: Index results
    Server-->>MCP: Status report
    MCP-->>Client: "42 documents indexed"
    
    Note over Client,FS: Search Flow
    Client->>MCP: "Search for brand guidelines"
    MCP->>Server: search_documents()
    Server->>DB: Query with filters
    DB-->>Server: Matching documents
    Server-->>MCP: Search results
    MCP-->>Client: Formatted results

______________________________________________________________________

✨ 特性

🎯 核心功能

• 🔍 智能搜索：所有内容的自然语言查询
• 🏷️ 智能分类：按类型和内容自动对文档进行分类
• 📊 实时索引：文档更改时自动更新
• 🔗 人工智能集成：原生支持Claude Desktop、Cursor IDE、VS代码
• 📁 多格式支持：Markdown、PDF、Word、YAML、JSON等

🧠 AI驱动的功能

• 🔍 语义搜索：基于向量的相似性匹配
• 🤖 ML分类：机器学习文档分类
• 📈 关系分析：发现文档之间的联系
• 💡 内容洞察：自动摘要和标签提取

🛡️ 企业就绪

• 🔐 安全：JWT身份验证和路径验证
• ⚡ 演出：缓存和后台处理
• 📊 监控：健康检查和使用分析
• 🔧 可配置的：适用于任何组织的灵活设置

______________________________________________________________________

⚡ 安装

先决条件

• Python 3.8+ （必填）
• Git （用于克隆存储库）
• 500MB闸板 最低（建议2GB以上）

自动安装

# Clone repository
git clone https://github.com/yourusername/brandnexus.git
cd brandnexus

# Run automated deployment
chmod +x deploy_mcp_server.sh
./deploy_mcp_server.sh

🔧 Manual Installation Steps

# 1. Install Python dependencies
pip install fastmcp sqlite3 pathlib pyyaml

# Optional: Enhanced document processing
pip install python-docx PyPDF2 markdown

# Optional: Advanced features
pip install scikit-learn sentence-transformers faiss-cpu

# 2. Create directory structure
mkdir -p strategy brand messaging templates guidelines

# 3. Initialize configuration
cp .env.example .env
# Edit .env with your specific paths

# 4. Initialize database
python domain_specific_mcp_server.py --init-db

验证

# Test server functionality
python domain_specific_mcp_server.py --health-check

# Expected output:
# ✅ Database connection: OK
# ✅ Document paths accessible: OK
# ✅ Server ready for MCP clients

______________________________________________________________________

⚙️ 配置

目录结构设置

按照以下结构组织文档：

your-project/
├── strategy/                    # 📈 Strategic documents
│   ├── company-strategy-2025.md
│   ├── product-roadmap.md
│   └── market-analysis.pdf
├── brand/                       # 🎨 Brand guidelines  
│   ├── brand-guidelines.md
│   ├── logo-usage.md
│   ├── color-palette.yaml
│   └── typography-guide.pdf
├── messaging/                   # 💬 Templates and copy
│   ├── email-templates/
│   ├── social-media-templates/
│   └── press-release-formats/
├── templates/                   # 📋 Additional templates
└── guidelines/                  # 📚 Other guidelines

环境配置

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

# Document paths (comma-separated)
DOCUMENT_PATHS=./strategy/,./brand/,./messaging/,./templates/,./guidelines/

# Database configuration
DATABASE_PATH=document_index.db

# Server settings
SERVER_NAME=BrandNexus Document Server
LOG_LEVEL=INFO

# Features
AUTO_REINDEX=true
REINDEX_INTERVAL=3600
ENABLE_SEMANTIC_SEARCH=false
ENABLE_ML_CLASSIFICATION=false

📄 Advanced Configuration (config.yaml)

server:
  name: "BrandNexus Document Server"
  version: "1.0.0"

paths:
  strategy: "./strategy/"
  brand: "./brand/"
  messaging: "./messaging/"

indexing:
  supported_extensions: [".md", ".txt", ".docx", ".pdf", ".yaml"]
  exclude_patterns: ["*.tmp", ".*", "__pycache__"]
  auto_reindex: true

classification:
  rules:
    strategy:
      path_patterns: ["/strategy/", "strategy"]
      keywords: ["roadmap", "objectives", "goals"]
    brand:
      path_patterns: ["/brand/", "brand"]  
      keywords: ["guidelines", "identity", "voice"]

______________________________________________________________________

🎯 用法

启动服务器

# Start as MCP server (stdio mode)
python domain_specific_mcp_server.py

# Or with custom configuration
python domain_specific_mcp_server.py --config config.yaml

基本操作

通过AI客户端连接后，使用自然语言：

📂 文档管理

"Index all documents"
"Refresh the document index" 
"Show indexing status"

🔍 搜索内容

"Find strategy documents about customer acquisition"
"Search for brand guidelines on logo usage"
"Show me messaging templates for product launches"
"Find all documents mentioning 'sustainability'"

📄 内容访问

"Get the content of our brand voice guide"
"Show me the latest strategy document"
"Display all email templates"

📊 分析和见解

"Analyze relationships between documents"
"Show document type distribution"
"What are the most common tags?"

文档类型

BrandNexus自动对文档进行分类：

______________________________________________________________________

🔌 客户端集成

克劳德桌面

🖥️ Setup Instructions

1. 安装克劳德桌面 从 Anthropic网站

1. 配置MCP服务器:

编辑 ~/.config/claude-desktop/claude_desktop_config.json:

   {
     "mcpServers": {
       "brandnexus": {
         "command": "python3",
         "args": ["/absolute/path/to/domain_specific_mcp_server.py"],
         "env": {
           "DOCUMENT_PATHS": "/path/to/strategy/,/path/to/brand/,/path/to/messaging/"
         }
       }
     }
   }

1. 重新启动克劳德桌面 并开始使用文档感知对话！

光标IDE

💻 Setup Instructions

1. 安装游标IDE 从 cursor.sh

1. 配置MCP集成:

创建 .cursor/mcp.json 在您的工作空间中：

   {
     "mcpServers": {
       "brandnexus": {
         "command": "python",
         "args": ["./domain_specific_mcp_server.py"],
         "env": {
           "DOCUMENT_PATHS": "./strategy/,./brand/,./messaging/"
         }
       }
     }
   }

1. 在游标中使用：在人工智能辅助下编码时访问文档

VS代码

🔧 Setup Instructions

1. 安装MCP扩展 （可用时）

1. 配置服务器:

创建 .vscode/mcp.json:

   {
     "servers": {
       "brandnexus": {
         "type": "stdio", 
         "command": "python",
         "args": ["./domain_specific_mcp_server.py"]
       }
     }
   }

______________________________________________________________________

📚 api参考

MCP工具

index_documents()

扫描并索引配置目录中的所有文档。

退货：

{
  "indexed": 42,
  "updated": 5,
  "errors": [],
  "document_types": {
    "strategy": 12,
    "brand_guideline": 8,
    "messaging_template": 22
  }
}

search_documents(query, document_type?, category?, limit?)

按内容、标题或元数据搜索文档。

参数：

• query （string）：搜索词
• document_type （可选）：按文档类型筛选
• category （可选）：按类别筛选
• limit （可选）：最大结果（默认值：10）

示例用法：

# Search for brand voice guidelines
search_documents("brand voice", document_type="brand_guideline", limit=5)

# Find all strategy documents mentioning "growth"
search_documents("growth", document_type="strategy")

get_document_content(path)

检索特定文档的完整内容。

例子：

get_document_content("/brand/brand-voice.md")

get_messaging_templates(category?)

返回可用的消息传递模板，可选择按类别筛选。

get_brand_guidelines(section?)

检索品牌指南，可选择按部分筛选。

analyze_document_relationships()

分析文档之间的关系和依赖关系。

MCP资源

通过结构化URI模式访问文档：

______________________________________________________________________

🔬 发展

开发环境设置

# Clone repository
git clone https://github.com/yourusername/brandnexus.git
cd brandnexus

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/

# Run linting
flake8 domain_specific_mcp_server.py
black domain_specific_mcp_server.py

项目结构

classDiagram
    class DocumentIndexer {
        +List~str~ base_paths
        +str db_path
        +init_database()
        +index_single_file(path)
        +search_content(query)
    }
    
    class DocumentMetadata {
        +str path
        +str title
        +str document_type
        +str category
        +datetime last_modified
        +List~str~ tags
    }
    
    class DocumentType {
        >
        STRATEGY
        BRAND_GUIDELINE
        MESSAGING_TEMPLATE
        POSITIONING
        CAMPAIGN_BRIEF
        BRAND_VOICE
    }
    
    class FastMCP {
        +str name
        +str instructions
        +run(transport)
    }
    
    DocumentIndexer --> DocumentMetadata
    DocumentIndexer --> DocumentType
    FastMCP --> DocumentIndexer
    
    note for DocumentIndexer "Core indexing engine\nwith SQLite backend"
    note for DocumentType "Automatically classified\nbased on path and content"

代码的风格

• Python代码遵循PEP 8
• 对所有公共函数使用类型提示
• 为所有公共方法添加文档字符串
• 最大行长：88个字符
• 使用 black 用于代码格式化

测试

# Run all tests
pytest

# Run with coverage
pytest --cov=domain_specific_mcp_server

# Run specific test category
pytest tests/test_indexing.py
pytest tests/test_search.py
pytest tests/test_mcp_tools.py

______________________________________________________________________

🚀 高级功能

机器学习分类

启用基于ML的文档分类：

# Install ML dependencies
pip install scikit-learn

# Enable in configuration
export ENABLE_ML_CLASSIFICATION=true

# Train classifier (requires ≥10 classified documents)
python -c "
from domain_specific_mcp_server import mcp
result = mcp.train_document_classifier()
print(result)
"

语义搜索

启用基于向量的语义搜索：

# Install semantic search dependencies  
pip install sentence-transformers faiss-cpu

# Enable in configuration
export ENABLE_SEMANTIC_SEARCH=true

使用示例：

# Hybrid search combining keywords and semantics
semantic_document_search(
    "company vision and strategic direction",
    semantic_weight=0.7,
    limit=10
)

实时监控

在文件更改时启用自动重新索引：

# Install file monitoring dependencies
pip install watchdog

# Enable in configuration
export AUTO_REINDEX=true

性能优化

对于大型文档集：

# Enable caching (10 minute TTL)
export CACHE_TTL=600

# Increase search limits  
export MAX_SEARCH_RESULTS=50

# Use background processing
export BACKGROUND_INDEXING=true

______________________________________________________________________

🛠️ 故障排除

常见问题

❌ 权限被拒绝错误

# Ensure read access to document directories
chmod -R 755 ./strategy/ ./brand/ ./messaging/

❌ 数据库锁定错误

# Close other connections and restart
python domain_specific_mcp_server.py --reset-db

❌ 未找到模块错误

# Reinstall dependencies
pip install --upgrade fastmcp sqlite3 pathlib pyyaml

❌ 未处理大文件

# Enable streaming for files >10MB
export ENABLE_STREAMING=true

调试模式

启用详细日志记录：

export DEBUG=true
export LOG_LEVEL=DEBUG
python domain_specific_mcp_server.py

健康检查

验证服务器状态：

from domain_specific_mcp_server import mcp
health = mcp.diagnose_server_health()
print(health)

获取帮助

1. 📋 检查日志：往里看 mcp_server.log 有关错误详细信息
2. ⚙️ 验证配置：确保路径和权限正确
3. 🧪 测试样品：使用提供的示例文件
4. 🔧 检查客户端：验证MCP客户端配置

性能问题

🚀 Optimization Tips

• 大型文档集：启用后台索引
• 搜索速度慢：实现结果缓存
• 内存使用：对大文件使用流媒体
• 数据库性能：常规真空操作

______________________________________________________________________

🤝 贡献

我们欢迎捐款！以下是如何开始：

🎯 贡献方式

• 🐛 错误报告：发现问题？ 打开一个问题
• 💡 功能请求：有主意吗？ 开始讨论
• 📝 文档：改进指南和示例
• 🧪 测试：扩大测试覆盖范围
• 🔧 代码：实现新功能或修复错误

开发工作流程

1. 分叉存储库 在GitHub上
2. 创建要素分支: git checkout -b feature/amazing-feature
3. 进行更改 并添加测试
4. 运行测试套件: pytest
5. 提交您的更改: git commit -m "Add amazing feature"
6. 推你的叉子: git push origin feature/amazing-feature
7. 打开拉取请求

🎯 优先领域

• \[ \] 新文档类型：支持其他文件格式
• \[ \] 增强分类：改进ML分类算法
• \[ \] 性能优化：优化索引和搜索
• \[ \] 安全功能：添加身份验证和授权
• \[ \] 用户界面组件：用于文档管理的Web界面

代码审查流程

• 所有更改都需要维护人员的审查
• 自动化测试必须通过
• 新功能的文档更新
• 遵循现有的代码风格和约定

______________________________________________________________________

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

MIT许可证摘要：

• ✅ 商业使用、修改、分发、私人使用
• ❌ 责任、保修

______________________________________________________________________

🙏 致谢

• Anthropic 用于模型上下文协议规范
• FastMCP 优秀的MCP服务器框架
• 贡献者 谁帮助BrandNexus变得更好
• 社区 用于反馈和功能请求

______________________________________________________________________

🗺️ Roadmap

🎯 版本2.0（2024年第二季度）

• \[ \] 多语言支持：国际文件处理
• \[ \] 高级分析：内容性能见解
• \[ \] 协作功能：团队工作流程和权限
• \[ \] 云部署：托管服务选项

🚀 版本2.1（2024年第三季度）

• \[ \] 基于人工智能的摘要：自动文档摘要
• \[ \] 版本控制集成：基于Git的文档跟踪
• \[ \] 高级可视化：交互式文档地图
• \[ \] API市场：第三方集成

______________________________________________________________________

由以下材料制成❤️ BrandNexus团队

🌐 网站 • 📖 文档 • 💬 社区 • 🐦 推特

*BrandNexus-将您的知识与人工智能驱动的工作流程联系起来*

______________________________________________________________________

*最后更新时间：2025年8月8日|根据代码库分析生成*