Portable MCP Toolkit

🚀 AIStack MCP

面向现代发展的企业级MCP编排

*双模MCP编排解决了隔离与协调的困境——本地优先，生产就绪，比纯云方法便宜90%。*

 ](https://github.com/mjdevaccount/AIStack-MCP/releases)    

______________________________________________________________________

📊 当前状态（v1.2.0）

最新版本： v1.2.0--MCP注册表集成和模板系统

v1.2.0的新增功能

快速统计

• 社区服务器：500+可通过注册表获得
• 模板：3种预构建配置
• 测试覆盖率：88个单元测试通过
• 文档：15+指南和故障排除文档
• 生产就绪：CI/CD验证，企业测试

______________________________________________________________________

💡 为何这很重要

问题： MCP服务器需要仔细隔离以确保安全，但现代开发通常跨越多个存储库。你不得不在两者之间做出选择 安全隔离 （一次一个回购）或 生产力 （交叉回购情报）。 解决方案： AIStack MCP提供 双模编排--使用单个命令在隔离的单回购模式和协调的多回购模式之间切换。两全其美。

关键差异化因素

______________________________________________________________________

📑 目录

• ✨ 特性
• 🏗️ 建筑
• 🚀 快速开始
• 📦 安装
• 🔄 操作模式
• 📖 使用指南
• 📁 项目结构
• 🛠️ 工具参考
• ⚡ 性能和成本
• 🔧 故障排除
• ❓ 常见问题解答
• 🎓 高级主题
• 🗺️ 路线图
• 🤝 贡献
• 📄 许可证

______________________________________________________________________

✨ 特性

核心能力

开发者体验

______________________________________________________________________

🏗️ 建筑

┌─────────────────────────────────────────────────────────────────────┐
│                    YOUR CODEBASE                                    │
│              (Any Language • Any Framework • Any Size)              │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                 AISTACK-MCP ORCHESTRATION LAYER                     │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐  │
│  │   Filesystem    │  │      Git        │  │  Code Intelligence  │  │
│  │      MCP        │  │      MCP        │  │        MCP          │  │
│  │  (Read/Write)   │  │  (History/Diff) │  │  (Search/Analyze)   │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────┘  │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  Mode Orchestrator: Single-Repo ←→ Multi-Repo Switching     │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    LOCAL AI STACK (FREE)                            │
│                                                                     │
│  ┌─────────────────────────┐    ┌─────────────────────────────┐    │
│  │        OLLAMA           │    │          QDRANT             │    │
│  │  • LLM Inference        │    │  • Vector Search            │    │
│  │  • Pattern Analysis     │    │  • Semantic Indexing        │    │
│  │  • Code Generation      │    │  • 90% Token Compression    │    │
│  └─────────────────────────┘    └─────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    CURSOR + CLAUDE                                  │
│           (Final Generation Only • Minimal Token Usage)             │
└─────────────────────────────────────────────────────────────────────┘

数据流和成本节约

1. 你问了一个问题 → 游标收到您的提示
2. 先本地搜索 → Qdrant查找相关代码块（免费）
3. 局部压缩 → Ollama总结上下文（免费）
4. 最小传输 → 仅向Claude发送了500-1000个代币
5. 最终世代 → 克劳德完全理解

结果： 令牌减少90%，质量相同，本地处理100%隐私。

______________________________________________________________________

🚀 快速开始

路径1：新用户（推荐）

# Clone and run the interactive wizard
git clone https://github.com/mjdevaccount/AIStack-MCP.git
cd AIStack-MCP
.\scripts\quickstart.ps1

向导会自动执行以下操作：

• ✅ 检查所有依赖关系
• ✅ 引导模式选择
• ✅ 配置服务
• ✅ 验证设置

路径2：经验丰富的用户

📋 Click to expand manual setup

# 1. Clone repository
git clone https://github.com/mjdevaccount/AIStack-MCP.git
cd AIStack-MCP

# 2. Install Python dependencies
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# 3. Start services
ollama serve                                    # Terminal 1
docker run -d -p 6333:6333 qdrant/qdrant       # Terminal 2

# 4. Pull required models
ollama pull mxbai-embed-large
ollama pull qwen2.5:7b

# 5. Configure mode
.\scripts\switch_to_single_repo.ps1

# 6. Open in Cursor
cursor .

路径3:CI/CD集成

# .github/workflows/validate.yml
- name: Validate MCP Configuration
  run: |
    python scripts/validate_mcp_config.py --test-generation --strict

______________________________________________________________________

🌐 社区工具（v1.2.0）

浏览500多台MCP服务器

搜索工具

.\scripts\list_registry_tools.ps1 -Search "database"

热门服务器

.\scripts\list_registry_tools.ps1 -Popular

安装社区工具

安装PostgreSQL服务器

.\scripts\install_community_tool.ps1 -ServerId "io.modelcontextprotocol/server-postgres"

安装Slack集成

.\scripts\install_community_tool.ps1 -ServerId "io.modelcontextprotocol/server-slack"

应用模板

最小（仅搜索）

.\scripts\apply_template.ps1 -Template minimal

标准（推荐）

.\scripts\apply_template.ps1 -Template standard

完整（所有功能）

.\scripts\apply_template.ps1 -Template full

看 注册表文件 完整指南。

______________________________________________________________________

📦 安装

系统要求

第一步：先决条件

# Install Node.js (for MCP community servers)
winget install OpenJS.NodeJS

# Install Python (if not present)
winget install Python.Python.3.11

# Verify installations
node --version   # Should show v18+
python --version # Should show 3.8+

第二步：Python依赖关系

cd C:\AIStack-MCP

# Create virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

第三步：本地人工智能服务

🦙 Ollama Setup

1. 下载自 奥拉玛
2. 安装并启动服务
3. 拉动所需型号：

ollama pull mxbai-embed-large  # Required: embeddings
ollama pull qwen2.5:7b         # Recommended: analysis
ollama pull phi4:14b           # Optional: code generation

1. 验证：

ollama list

🔍 Qdrant Setup

选项A:Docker（推荐）

docker run -d -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant

选项B：本机安装

• 下载自 qdrant.tech

验证：

curl http://localhost:6333/collections

步骤4：配置

# Run the quickstart wizard (recommended)
.\scripts\quickstart.ps1

# Or manually configure single-repo mode
.\scripts\switch_to_single_repo.ps1

💡 提示： 如果Cursor在启动时挂起，请确保您正在使用 cmd /c 包装图案。看 Windows MCP修复程序.

______________________________________________________________________

🔄 操作模式

模式比较

切换模式

# Switch to single-repo (isolated, portable)
.\scripts\switch_to_single_repo.ps1

# Switch to multi-repo (orchestrated)
.\scripts\switch_to_multi_repo.ps1

# Check current mode
Get-Content .cursor\ACTIVE_MODE.txt

多回购设置

# 1. Link repositories (requires Admin for symlinks)
.\scripts\link_repo.ps1 -TargetPath "C:\Projects\backend-api"
.\scripts\link_repo.ps1 -TargetPath "C:\Projects\frontend-app"

# 2. Or clone directly (no Admin required)
.\scripts\link_repo.ps1 -TargetPath "https://github.com/org/repo" -Clone

# 3. Activate multi-repo mode
.\scripts\switch_to_multi_repo.ps1

# 4. Restart Cursor

______________________________________________________________________

📖 使用指南

场景1：首次设置

# 1. Run quickstart wizard
.\scripts\quickstart.ps1

# 2. Open project in Cursor
cursor C:\AIStack-MCP

# 3. In Cursor chat, index your workspace
Use code-intelligence to index_workspace

# 4. Verify setup
Use code-intelligence to validate_workspace_config

预期产量：

✅ Workspace: C:\AIStack-MCP (accessible)
✅ Ollama: Connected (3 models available)
✅ Qdrant: Connected (1 collection indexed)
✅ Configuration: Valid

场景2：日常开发

# Semantic search (find code by meaning)
Use code-intelligence to semantic_search for "error handling patterns"

# Pattern analysis (extract patterns with LLM)
Use code-intelligence to analyze_patterns for "async"

# Get optimized context for a file
Use code-intelligence to get_context for src/utils.py with task "add retry logic"

# Generate code matching project style
Use code-intelligence to generate_code for src/api.py with task "add pagination"

场景3：多回购开发

# Morning: Link all related repos
.\scripts\link_repo.ps1 -TargetPath "C:\Projects\shared-libs"
.\scripts\link_repo.ps1 -TargetPath "C:\Projects\backend"
.\scripts\link_repo.ps1 -TargetPath "C:\Projects\frontend"

# Activate multi-repo mode
.\scripts\switch_to_multi_repo.ps1

# Now in Cursor: search across ALL linked repos
Use code-intelligence to semantic_search for "authentication flow"

场景4：团队入职

与新团队成员共享以下命令：

# Complete setup in one command
git clone https://github.com/your-org/AIStack-MCP.git
cd AIStack-MCP
.\scripts\quickstart.ps1

参考： docs/BEST_PRACTICES.md

______________________________________________________________________

📁 项目结构

AIStack-MCP/
├── .cursor/
│   ├── mcp.json                  # 🎯 Active MCP configuration
│   └── ACTIVE_MODE.txt           # 📍 Current mode indicator
│
├── docs/
│   ├── WORKSPACE_PATTERN.md      # 📐 Isolation best practices
│   ├── BEST_PRACTICES.md         # 👥 Team usage guidelines
│   ├── SETUP.md                  # 📋 Detailed setup guide
│   └── troubleshooting/          # 🔧 Platform-specific fixes
│       ├── WINDOWS_MCP_FIX.md
│       └── MCP_TROUBLESHOOTING.md
│
├── scripts/
│   ├── quickstart.ps1            # 🌟 Interactive setup wizard
│   ├── switch_to_single_repo.ps1 # 🔒 Activate isolated mode
│   ├── switch_to_multi_repo.ps1  # 🌐 Activate orchestration mode
│   ├── link_repo.ps1             # 🔗 Repository linking helper
│   ├── validate_mcp_config.py    # ✅ CI-ready validation
│   ├── validate_workspace.py     # 🩺 Workspace diagnostics
│   ├── dev_all.ps1               # 📊 Dev environment status
│   └── mcp_config_builder.py     # 🏗️ Config generator
│
├── workspaces/                   # 📂 Multi-repo links (gitignored)
│   └── README.md
│
├── python_agent/                 # 🤖 Agent implementation
│   ├── agents/
│   ├── tools/
│   └── mcp_production_server.py
│
├── mcp_intelligence_server.py    # 🧠 Main MCP server
├── requirements.txt              # 📦 Python dependencies
├── docker-compose.yml            # 🐳 Service orchestration
└── README.md                     # 📖 You are here

______________________________________________________________________

🛠️ 工具参考

可用的MCP工具

何时使用每种工具

______________________________________________________________________

⚡ 性能和成本

现实世界指标

How is this different from GitHub Copilot?

Copilot提供在线完井。AIStack MCP提供：

• 语义搜索 在整个代码库中
• 模式分析 使用本地LLM
• 交叉回购情报 在多回购模式下
• 成本降低90% 通过局部预处理
• 100%隐私 用于本地处理

它们相辅相成——两者兼得！

Why local-first instead of cloud-only?

• 成本： 本地LLM推理是免费的
• 隐私： 代码永远不会离开你的机器进行搜索/分析
• 速度： 矢量搜索与网络延迟相比\

Can I use this with VS Code?

目前已针对Cursor IDE进行了优化。VS Code支持已在路线图上（v1.1）。

What languages are supported?

全部！该系统适用于任何基于文本的代码：

• Python、JavaScript、TypeScript
• Rust、Go、Java、C#、C++
• Ruby、PHP、Swift、Kotlin
• 还有更多。..

Is this production-ready?

对。AIStack MCP包括：

• CI就绪验证脚本
• 全面的错误处理
• 健康监测
• 生产测试配置
• 企业安全模式

What about security?

• 单回购模式： 每个项目权限的最大隔离
• 多回购模式： 需要显式链接，控制CORE工作区
• 本地处理： 敏感代码永远不会离开你的机器
• 审计跟踪： .cursor/ACTIVE_MODE.txt 跟踪模式更改

看 docs/BEST_PRACTICES.md 安全指南。

Can teams use this?

当然！共享存储库并让团队成员运行：

.\scripts\quickstart.ps1

看 docs/BEST_PRACTICES.md 用于团队工作流程。

How do I update to new versions?

git pull origin main
pip install -r requirements.txt --upgrade
.\scripts\switch_to_single_repo.ps1  # Regenerate config

______________________________________________________________________

🎓 高级主题

1.多回购编排模式

何时使用多重回购模式：

• Python多包项目
• 微服务架构
• 具有独立仓库的Monrepo风格开发

链接策略：

• 符号链接： 最适合当地发展（需要管理员）
• 克隆： 无需管理员，独立副本
• 子模块： 版本控制链接

📖 完整指南

2.CI/CD集成

# .github/workflows/validate.yml
name: Validate MCP Config
on: [push, pull_request]
jobs:
  validate:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -r requirements.txt
      - run: python scripts/validate_mcp_config.py --test-generation --strict

3.定制工具开发

扩展 mcp_intelligence_server.py:

@mcp.tool()
async def my_custom_tool(query: str) -> str:
    """Your custom tool description."""
    # Implementation
    return result

4.团队工作流程

模式选择决策树：

Working on ONE repo? → Single-repo mode
Working on 2-5 related repos? → Multi-repo mode
Working on 6+ repos? → Split into focused workspaces

📖 完整指南

5.生产部署

# docker-compose.yml (included)
services:
  qdrant:
    image: qdrant/qdrant
    ports:
      - "6333:6333"
    volumes:
      - qdrant_storage:/qdrant/storage

______________________________________________________________________

🗺️ 路线图

v1.2.0--当前版本✅

• ✅ MCP注册表集成（浏览500多个社区服务器）
• ✅ 模板系统（最小、标准、完整）
• ✅ 服务器安装程序（npm、PyPI、Docker）
• ✅ 社区工具管理脚本
• ✅ 双模式编排（单/多仓库）
• ✅ 完整的验证套件
• ✅ 交互式设置向导
• ✅ 生产就绪模式
• ✅ 全面的文件

v1.3.0--计划中

• 🔲 VS代码扩展支持
• 🔲 额外的LLM后端（克劳德本地，GPT4All）
• 🔲 增强的缓存层
• 🔲 仪表盘

v2.0.0--未来

• 🔲 可选云同步
• 🔲 团队协作功能
• 🔲 管理员仪表板
• 🔲 使用情况分析

______________________________________________________________________

🤝 贡献

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

报告Bug

打开一个问题 与：

• 问题的清晰描述
• 重现步骤
• 预期行为与实际行为
• 系统信息（操作系统、Python版本等）

功能请求

展开讨论 以提出新功能。

开发设置

# Fork and clone
git clone https://github.com/YOUR_USERNAME/AIStack-MCP.git
cd AIStack-MCP

# Install dependencies
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# Run validation
python scripts\validate_mcp_config.py --test-generation

拉取请求流程

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行验证(python scripts\validate_mcp_config.py --strict)
5. 承诺(git commit -m 'feat: Add amazing feature')
6. 推(git push origin feature/amazing-feature)
7. 打开拉取请求

编码标准

• PowerShell：关注 PSScriptAnalyzer 规则
• 承诺：使用 常规承诺

______________________________________________________________________

🙏 致谢

这个项目站在巨人的肩膀上：

• 模型上下文协议 --AI-IDE集成的基础
• MCP社区服务器 --文件系统、Git、GitHub实现
• 奥拉玛 --本地LLM推理变得简单
• Qdrant --高性能矢量搜索
• 光标 --AI第一IDE

______________________________________________________________________

🔗 相关项目

• MCP规范 --协议文件
• MCP服务器 --官方服务器实施
• 奥拉玛 --在本地运行LLM
• Qdrant --向量相似性搜索

______________________________________________________________________

📄 许可证

该项目根据 MIT许可证 --看看 许可证 文件以获取详细信息。

MIT License

Copyright (c) 2025 AIStack-MCP Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

______________________________________________________________________

⭐ 如果这个回购对你有帮助，请加星！

](https://github.com/mjdevaccount/AIStack-MCP/stargazers) ](https://github.com/mjdevaccount/AIStack-MCP/network/members)

由以下材料制成❤️ 对于MCP社区