使用说明

🚀 SharePoint MCP服务器-下一代

A. 下一代MCP服务器 实现与Microsoft SharePoint的无缝集成，同时提供传统的MCP协议支持和现代API功能。使用JavaScript/Node.js构建，以提高效率和企业级安全性。

� 基于原创作品：这个项目的灵感来自并建立在优秀的 mcp共享点 Sofias ai的Python实现。

🔄 增强的JavaScript端口：我们用JavaScript完全重写了代码库，并添加了显著的增强功能：

🔐 增强的安全性：从客户端密钥升级到基于证书的身份验证

🏗️ 双模架构：在传统MCP的基础上增加了HTTP/WebSocket API服务器

🛡️ 企业安全：带有自定义API令牌的服务器端凭据存储

🚀 生产就绪：Docker、PM2和systemd部署配置

🌐 多客户端支持：通过HTTP/WebSocket同时进行客户端连接

🎯 我们建造了什么

🏗️ 双模架构

模式1：传统MCP服务器

✅ 100%符合MCP协议 -与Claude Desktop配合使用
✅ 标准通信 -标准MCP传输
✅ 基于工具的界面 -用于SharePoint操作的注册MCP工具

模式2：安全的API服务器

✅ HTTP REST API -所有SharePoint操作的RESTful端点
✅ WebSocket支持 -实时通信能力
✅ 自定义身份验证 -您自己的API令牌，而不是SharePoint凭据
✅ 多客户端支持 -多个客户端可以同时连接
✅ 企业安全 -服务器端凭据存储

✨ 主要特点

📁 完成CRUD操作

� READ -列出文件夹、浏览文档、获取内容、浏览树
� 创建 -上传文档、创建文件夹、组织内容
✏️ 更新 -修改文档内容，更新文件属性
🗑️ 删除 -通过全面清理删除文件和文件夹
🌳 树导航 -具有可配置深度的递归文件夹结构
🔍 内容访问 -具有自动文本/二进制检测功能的文档内容
🏷️ 元数据 -文件属性、大小、修改日期、SharePoint URL

🔐 安全和身份验证

🔒 证书身份验证 -基于X.509证书的安全身份验证
🛡️ 服务器端凭据 -SharePoint凭据永远不会离开服务器
🎫 自定义API令牌 -生成自己的身份验证令牌
🔑 许可证管理 -针对不同客户端/环境的多个令牌
🚫 零凭证风险 -客户只需要您的自定义令牌

🚀 部署选项

🐳 Docker支持 -集装箱化部署
⚙️ PM2配置 -生产过程管理
🔄 系统化服务 -Linux服务集成
📊 健康监测 -内置健康检查和日志记录

🛠️ 可用操作

传统MCP工具（克劳德桌面）

List_SharePoint_Folders -列出指定目录中的文件夹
List_SharePoint_Documents -列出文件夹中的文档
Get_SharePoint_Tree -获取递归文件夹树结构
Get_SharePoint_Document_Content -读取文档内容
Create_SharePoint_Folder -创建新文件夹
Upload_SharePoint_Document -上传文件
Upload_SharePoint_Document_From_Path -从本地路径上传
Update_SharePoint_Document -更新现有文档
Delete_SharePoint_Item -删除文件或文件夹

API服务器终结点（HTTP/WebSocket）

📖 读取操作：

GET /api/folders -列出文件夹
GET /api/documents -列出文件
GET /api/tree -获取文件夹树
GET /api/document/:path/content -获取文档内容

📝 创建操作：

POST /api/upload -上传文件
POST /api/folder -创建新文件夹

✏️ 更新操作：

PUT /api/document/:path -更新文档内容

🗑️ 删除操作：

DELETE /api/item/:path -删除任何文件或文件夹
DELETE /api/document/:path -删除文档（别名）
DELETE /api/folder/:path -删除文件夹（别名）
POST /api/upload -上传文件
GET /health -服务器健康检查

🚀 快速开始

1.安装

git clone <your-repo>
cd sharePointMCP
npm install

2.环境设置

# Copy environment template
cp .env.example .env

# Edit .env with your values:
SHP_ID_APP=your-azure-app-id
SHP_SITE_URL=https://your-tenant.sharepoint.com/sites/your-site
SHP_TENANT_ID=your-tenant-id
SHP_CERT_PFX_PATH=./certificate.pfx
SHP_CERT_PFX_PASSWORD=your-cert-password

# For API mode, add custom tokens:
API_AUTH_TOKENS=your-secret-token-1,your-secret-token-2

3.运行服务器

MCP模式（克劳德桌面）

npm run start:mcp

API模式（HTTP/WebSocket）

npm run start:api
# Server will be available at http://localhost:3000

📋 用法示例

Claude桌面集成

添加到您的 mcp.json:

{
  "mcpServers": {
    "sharepoint": {
      "command": "node",
      "args": ["/path/to/sharePointMCP/src/server.js", "mcp"]
    }
  }
}

HTTP API使用情况

# List folders (with authentication)
curl -H "Authorization: Bearer your-api-token" \
     http://localhost:3000/api/folders

# Get document content
curl -H "Authorization: Bearer your-api-token" \
     http://localhost:3000/api/document/MyFile.txt/content

# Get folder tree
curl -H "Authorization: Bearer your-api-token" \
     "http://localhost:3000/api/tree?maxDepth=3"

JavaScript客户端示例

import axios from 'axios';

const client = axios.create({
  baseURL: 'http://localhost:3000',
  headers: { 'Authorization': 'Bearer your-api-token' }
});

// List folders
const folders = await client.get('/api/folders');

// Get document content
const content = await client.get('/api/document/report.pdf/content');

WebSocket示例

const ws = new WebSocket('ws://localhost:3000?token=your-api-token');

ws.send(JSON.stringify({
  action: 'listFolders',
  params: { parentFolder: 'Documents' }
}));

ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Folders:', response);
};

🔧 环境变量

SharePoint配置

SHP_ID_APP=your-azure-app-id               # Azure AD Application ID
SHP_SITE_URL=https://tenant.sharepoint.com # SharePoint site URL
SHP_DOC_LIBRARY=Shared Documents           # Document library path
SHP_TENANT_ID=your-tenant-id               # Microsoft tenant ID
SHP_CERT_PFX_PATH=./certificate.pfx        # Certificate file path
SHP_CERT_PFX_PASSWORD=cert-password        # Certificate password

服务器配置

SERVER_MODE=api                             # Mode: 'mcp' or 'api'
PORT=3000                                   # API server port
API_AUTH_TOKENS=token1,token2,token3        # Custom authentication tokens
NODE_ENV=production                         # Environment mode

操作设置

SHP_MAX_DEPTH=15                           # Maximum folder tree depth
SHP_MAX_FOLDERS_PER_LEVEL=100              # Max folders per level
SHP_LEVEL_DELAY=0.5                        # Delay between levels (seconds)

� 服务器端凭据管理

🛡️ 为什么是服务器端凭据？

此MCP服务器实现 企业级安全 通过在服务器上安全地存储SharePoint凭据并提供您自己的API身份验证令牌。这种方法有几个优点：

🔒 增强的安全性 -SharePoint凭据永远不会离开服务器
🎫 自定义身份验证 -生成您自己的API令牌
🔄 轻松旋转 -在不接触客户端配置的情况下更新凭据
📊 审计跟踪 -使用您自己的代币跟踪API使用情况
🚀 可扩展性 -多个客户端可以使用相同的SharePoint连接

📁 安全配置结构

/opt/sharepoint-mcp/                    # Production directory structure
├── config/
│   └── .env.production                 # Environment variables (600 permissions)
├── certs/
│   └── certificate.pfx                 # X.509 certificate (600 permissions)
├── src/                               # Application source code
├── logs/                              # Application logs
└── scripts/                           # Deployment scripts

⚙️ 配置管理

服务器使用 安全配置加载器 即：

验证所有凭据 开始前
检查证书文件权限 以及可访问性
验证Azure AD配置 （GUID、URL）
测试SharePoint连接 启动期间
提供详细的错误消息 用于故障排除

🚀 快速设置命令

# 1. Validate your configuration and credentials
npm run validate

# 2. Set up secure deployment structure
npm run setup:secure

# 3. Configure systemd service (Linux)
npm run setup:systemd

# 4. Start with validated configuration
npm start

🔧 环境文件结构

创建 .env.production 使用您的服务器凭据：

# SharePoint Configuration
SHP_ID_APP=12345678-1234-1234-1234-123456789012
SHP_TENANT_ID=87654321-4321-4321-4321-210987654321  
SHP_SITE_URL=https://your-tenant.sharepoint.com/sites/your-site
SHP_CERT_PFX_PATH=/opt/sharepoint-mcp/certs/certificate.pfx
SHP_CERT_PFX_PASSWORD=your-certificate-password

# Server Configuration  
SERVER_MODE=api                                      # or 'mcp' for MCP-only
PORT=3000
LOG_LEVEL=info

# API Security (Generate with: openssl rand -hex 32)
API_AUTH_TOKENS=64-char-token-1,64-char-token-2
CORS_ORIGINS=https://your-domain.com
RATE_LIMIT_WINDOW=900000                            # 15 minutes
RATE_LIMIT_MAX=100                                  # requests per window

🔍 凭证验证

启动服务器之前，请验证您的设置：

npm run validate

此全面验证检查：

✅ 配置文件语法和所需值
✅ 证书文件存在和权限
✅ SharePoint身份验证和连接
✅ 文件系统权限和安全
✅ 与Microsoft Graph API的网络连接

⚡ 生产部署

# 1. Set up secure directory structure
sudo ./scripts/setup-secure-deployment.sh

# 2. Copy your files to secure locations
sudo cp certificate.pfx /opt/sharepoint-mcp/certs/
sudo cp .env.production /opt/sharepoint-mcp/config/

# 3. Set secure file permissions  
sudo chmod 600 /opt/sharepoint-mcp/certs/certificate.pfx
sudo chmod 600 /opt/sharepoint-mcp/config/.env.production

# 4. Configure systemd service
sudo ./scripts/deploy-systemd.sh

# 5. Start the service
sudo systemctl start sharepoint-mcp

🎫 客户端身份验证

客户端使用以下方式进行身份验证 您的自定义API令牌 而不是SharePoint凭据：

// HTTP API Authentication
const response = await fetch('http://your-server:3000/api/folders', {
  headers: { 'Authorization': 'Bearer your-custom-token' }
});

// WebSocket Authentication  
const ws = new WebSocket('ws://your-server:3000?token=your-custom-token');

优点：

🔒 SharePoint凭据保留在服务器上
🎛️ 使用您自己的令牌控制访问
🔄 在不更新SharePoint的情况下旋转令牌
📊 按令牌/客户端跟踪使用情况

�🐳 部署选项

Docker部署

# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t mcp-sharepoint .
docker run -d --env-file .env mcp-sharepoint

PM2过程经理

# Install PM2 globally
npm install -g pm2

# Start both MCP and API servers
pm2 start ecosystem.config.json

# Or start individual services
# Start API server only
pm2 start ecosystem.config.json --only sharepoint-mcp-api
pm2 start ecosystem.config.json --only sharepoint-mcp-stdio

系统化服务

# Copy service file
sudo cp mcp-sharepoint.service /etc/systemd/system/

# Enable and start service
sudo systemctl enable mcp-sharepoint
sudo systemctl start mcp-sharepoint

🔐 安全功能

✅ 企业级安全

服务器端凭据 -SharePoint凭据从未向客户端公开
自定义身份验证 -生成您自己的API令牌
基于证书的身份验证 -使用Azure进行X.509证书身份验证
代币轮换 -易于令牌管理和轮换
访问控制 -针对不同访问级别的多个令牌

✅ 部署安全

环境变量 -环境中的敏感数据，而非代码
Docker的秘密 -容器秘密管理
文件权限 -限制证书文件访问
进程隔离 -非root用户执行

📊 架构优势

🔄 传统MCP与增强型API

功能	传统MCP	我们的增强型服务器
协议遵从	✅ MCP标准	✅ MCP+HTTP+WebSocket
客户支持	🔒 单曲（克劳德）	🌐 多个并发
认证	😰 凭据已暴露	🔐 仅限自定义令牌
部署	🏠 仅限本地	☁️ 服务器/云就绪
运输	📡 仅限标准	🚀 Stdio+HTTP+WebSocket
安全模型	⚠️ 客户端信誉	🛡️ 服务器端安全

🏗️ 技术架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │◄──►│  Dual-Mode       │◄──►│   SharePoint    │
│ (Claude Desktop)│    │  Server          │    │   Graph API     │
└─────────────────┘    │                  │    └─────────────────┘
                       │  ┌─────────────┐ │
┌─────────────────┐    │  │   MCP Core  │ │
│  HTTP Client    │◄──►│  └─────────────┘ │
└─────────────────┘    │  ┌─────────────┐ │
                       │  │  API Server │ │
┌─────────────────┐    │  └─────────────┘ │
│ WebSocket Client│◄──►│  ┌─────────────┐ │
└─────────────────┘    │  │ Auth Layer  │ │
                       │  └─────────────┘ │
                       └──────────────────┘

🧪 测试与验证

测试安装

# Test MCP mode
npm test

# Test API mode
npm run dev:api
curl http://localhost:3000/health

测试内容

✅ 认证 -基于证书的Azure身份验证工作
✅ SharePoint访问 -已成功连接到SharePoint网站
✅ 文件夹操作 -正确列出文件夹和文档
✅ API终点 -HTTP端点以正确的数据响应
✅ 安全 -自定义令牌身份验证功能
✅ MCP合规性 -与Claude Desktop集成兼容

📈 我们取得的成就

🎯 从Python到JavaScript——关键改进

Aspect	原始Python版本	我们增强的JavaScript版本
语言	🐍 python⚡ JavaScript/Node.js
认证	🔑 客户端密码	🔐 X.509证书
建筑	📡 仅限MCP	🏗️ 双模式（MCP+neneneba API）
客户支持	🔒 单客户端	🌐 多客户端
运输	📨 仅限标准	🚀 Stdio+HTTP+WebSocket
安全模型	⚠️ 配置中的凭据	🛡️ 服务器端+自定义令牌
部署	🏠 地方发展	☁️ 生产就绪
身份验证暴露	😰 客户端秘密	🔐 零凭证风险

🚀 超越原作

✅ 完成语言迁移 -完整Python→ JavaScript转换
✅ 增强的安全性 -基于证书的身份验证+服务器端凭据保护
✅ 现代建筑 -HTTP/WebSocket API服务器功能
✅ 生产部署 -Docker、PM2、systemd配置
✅ 企业功能 -多客户端支持，自定义身份验证
✅ 开发者体验 -多种集成模式和示例

🙏 原作者署名

特别感谢索菲亚艾团队创建了基础Python SharePoint MCP服务器，激发了这种增强的JavaScript实现。他们的工作为我们构建和扩展的SharePoint集成模式和MCP工具定义提供了蓝图。

🔮 未来的可能性

计划中的增强功能

🔄 实时同步 -基于WebSocket的文件更改通知
🎯 高级权限 -每个文件夹/操作的基于令牌的访问控制
📊 分析仪表板 -使用监控和分析
🔌 插件系统 -可扩展操作插件
🌐 多住户 -每个实例支持多个SharePoint网站

整合机会

🤖 AI助理 -Beyond Claude（OpenAI、Anthropic等）
🔗 网络钩子 -SharePoint更改通知
📱 移动SDK -原生移动应用集成
🌍 GraphQL API -现代GraphQL端点
🔄 同步服务 -双向文件同步

🤝 贡献

我们欢迎捐款！该项目展示了：

现代JavaScript/Node.js模式
MCP协议实现
企业安全实践
多模式服务器架构

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🎉 成功案例

从Python到具有企业安全性的生产就绪JavaScript MCP服务器！ 🚀

该项目成功地演示了如何构建下一代MCP服务器，该服务器在添加现代API功能和企业级安全功能的同时保持完全的协议遵从性。

可选配置变量

SHP_MAX_DEPTH：树操作的最大文件夹深度（默认值：15）
SHP_MAX_FOLDERS_PER_LEVEL：每个级别要处理的最大文件夹数（默认值：100）
SHP_LEVEL_DELAY：处理级别之间的延迟（秒）（默认值：0.5）

安装

先决条件

Node.js 18+
npm或纱线
具有SharePoint权限的已注册Azure AD应用程序
用于身份验证的证书（PFX格式）

从源代码安装

# Clone the repository
git clone <repository-url>
cd sharePointMCP

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

用法

运行服务器

# Development mode (with TypeScript compilation)
npm run dev

# Production mode (compiled JavaScript)
npm start

Claude桌面集成

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "sharepoint": {
      "command": "node",
      "args": ["/path/to/sharePointMCP/dist/index.js"],
      "env": {
        "SHP_ID_APP": "your-app-id",
        "SHP_SITE_URL": "https://your-tenant.sharepoint.com/sites/your-site",
        "SHP_DOC_LIBRARY": "Shared Documents/your-folder",
        "SHP_TENANT_ID": "your-tenant-id",
        "SHP_CERT_PFX_PATH": "./certificate.pfx",
        "SHP_CERT_PFX_PASSWORD": "your-cert-password",
        "SHP_MAX_DEPTH": "15",
        "SHP_MAX_FOLDERS_PER_LEVEL": "100",
        "SHP_LEVEL_DELAY": "0.5"
      }
    }
  }
}

可用工具

📁 文件夹操作

列表_ SharePoint _文件夹：列出目录中的文件夹
Get_SharePoint_Tree：获取递归文件夹结构
创建文件夹（_Folder）：创建新文件夹
删除文件夹：删除空文件夹

📄 文档操作

列表_ SharePoint _文档：列出文件夹中的文档
获取_文档_内容：读取文档内容（文本/二进制）
上传_文档：从内容上传文件
上传_文档_来源_路径：从本地路径上载文件
更新_文档：更新现有文件
删除_文档：删除文档
下载_文档：将文件下载到本地系统

发展

需求

Node.js 18+
TypeScript 5+
中列出的依赖关系 package.json

地方发展

克隆存储库
安装依赖项：
```
npm install
```
创建一个 .env 包含SharePoint凭据的文件（使用 .env.example 作为模板）
构建并运行：
```
npm run build
npm start
```

🧪 API使用示例

认证

所有API端点都需要身份验证。使用您的API令牌：

# Set your API token
export API_TOKEN="your-64-character-api-token-here"
export SERVER_URL="https://your-server.onrender.com"

📖 读取操作

# List all folders
curl -H "Authorization: Bearer $API_TOKEN" "$SERVER_URL/api/folders"

# List documents in a specific folder
curl -H "Authorization: Bearer $API_TOKEN" "$SERVER_URL/api/documents?folderName=General"

# Get folder tree structure
curl -H "Authorization: Bearer $API_TOKEN" "$SERVER_URL/api/tree"

# Get document content
curl -H "Authorization: Bearer $API_TOKEN" "$SERVER_URL/api/document/test.txt/content"

📝 创建操作

# Upload a document (JSON-based)
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "hello-world.txt",
    "content": "Hello from SharePoint MCP!",
    "folderPath": ""
  }' \
  "$SERVER_URL/api/upload"

# Create a new folder
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "folderName": "New Project",
    "parentPath": ""
  }' \
  "$SERVER_URL/api/folder"

✏️ 更新操作

# Update document content
curl -X PUT \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated content for the document"
  }' \
  "$SERVER_URL/api/document/hello-world.txt"

🗑️ 删除操作

# Delete a document
curl -X DELETE \
  -H "Authorization: Bearer $API_TOKEN" \
  "$SERVER_URL/api/document/hello-world.txt"

# Delete a folder
curl -X DELETE \
  -H "Authorization: Bearer $API_TOKEN" \
  "$SERVER_URL/api/folder/Old%20Project"

# Delete any item (universal endpoint)
curl -X DELETE \
  -H "Authorization: Bearer $API_TOKEN" \
  "$SERVER_URL/api/item/path/to/item"

🏥 健康检查

# Check server status
curl "$SERVER_URL/health"

# Validate API token
curl -H "Authorization: Bearer $API_TOKEN" "$SERVER_URL/api/auth/validate"

# List all available endpoints
curl -H "Authorization: Bearer $API_TOKEN" "$SERVER_URL/api"

测试

# Run tests
npm test

调试

为了调试MCP服务器，您可以使用 MCP检查员:

npx @modelcontextprotocol/inspector -- node dist/index.js

安全考虑

安全地存储证书，永远不要将其提交给版本控制
对所有敏感配置使用环境变量
定期轮换证书和访问令牌
遵循组织的SharePoint访问安全策略

贡献

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

许可证

MIT许可证。有关详细信息，请参阅LICENSE文件。

支持

对于问题和疑问：

检查现有问题
创建包含详细信息的新问题
包括日志和配置（编辑敏感信息）

与Python版本的差异

此JavaScript/TypeScript版本保持了与原始Python版本的功能对等，同时提供：

更好的Node.js集成 对于JavaScript优先的环境
类型安全性 使用TypeScript
现代async/await 图案贯穿始终
改进了错误处理 使用结构化日志记录
NPM生态系统 访问附加功能
更快的启动时间 在某些环境中

使用说明

🚀 SharePoint MCP服务器-下一代

🎯 我们建造了什么

🏗️ 双模架构

模式1：传统MCP服务器

模式2：安全的API服务器

✨ 主要特点

📁 完成CRUD操作

🔐 安全和身份验证

🚀 部署选项

🛠️ 可用操作

传统MCP工具 （克劳德桌面）

API服务器终结点 （HTTP/WebSocket）

🚀 快速开始

1.安装

2.环境设置

3.运行服务器

MCP模式（克劳德桌面）

API模式（HTTP/WebSocket）

📋 用法示例

Claude桌面集成

HTTP API使用情况

JavaScript客户端示例

WebSocket示例

🔧 环境变量

SharePoint配置

服务器配置

操作设置

� 服务器端凭据管理

🛡️ 为什么是服务器端凭据？

📁 安全配置结构

⚙️ 配置管理

🚀 快速设置命令

🔧 环境文件结构

🔍 凭证验证

⚡ 生产部署

🎫 客户端身份验证

�🐳 部署选项

Docker部署

PM2过程经理

系统化服务

🔐 安全功能

✅ 企业级安全

✅ 部署安全

📊 架构优势

🔄 传统MCP与增强型API

🏗️ 技术架构

🧪 测试与验证

测试安装

测试内容

📈 我们取得的成就

🎯 从Python到JavaScript——关键改进

🚀 超越原作

🙏 原作者署名

🔮 未来的可能性

计划中的增强功能

整合机会

🤝 贡献

📄 许可证

🎉 成功案例

可选配置变量

安装

先决条件

从源代码安装

用法

运行服务器

Claude桌面集成

可用工具

📁 文件夹操作

📄 文档操作

发展

需求

地方发展

🧪 API使用示例

认证

📖 读取操作

📝 创建操作

✏️ 更新操作

🗑️ 删除操作

🏥 健康检查

传统MCP工具（克劳德桌面）

API服务器终结点（HTTP/WebSocket）