AI导哈

企业协作API服务

一个集成了日程管理、会议室预约、邮件管理、用户目录、任务管理等功能的企业内部协作API服务平台。

  • by larvine
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 larvine/nox-mcp

使用说明

企业协作MCP服务器

公司collab.v1 （或corp.workspace.v1）

内部公共MCP服务器，集成并提供企业协作API，如日历/电子邮件/会议室。

技术堆栈

  • FastMCP：FastAPI风格的基于装饰器的MCP服务器框架
  • 派丹蒂克：类型安全性和数据验证
  • Python 3.10+：利用最新的Python功能

概述

该MCP服务器提供了多种内部协作工具作为一个集成的界面：

  • 日程安排：创建会议、检索可用时间、管理与会者
  • 会议室预订：检查会议室、预订和可用性
  • 电子邮件：发送邮件、草稿管理、主题查询
  • 目录：搜索用户/组，身份规范化（四号/邮件/别名→标准ID）
  • 管理任务：TODO/问题注册（Jira、Notion等适配器）
  • 文件：链接文档，验证权限（可选）
  • 策略：工作时间、休息日、权限、垃圾邮件/批量发送限制
  • 实用程序：时区转换、ICS生成、健康检查、幂等

项目结构

src/corp_collab_mcp/
├── namespaces/          # 네임스페이스별 구현
│   ├── meetings/        # 일정/슬롯/이벤트
│   ├── rooms/           # 회의실/가용성/예약
│   ├── mail/            # 메일 전송/드래프트/스레드
│   ├── directory/       # 사용자/그룹 검색·정규화
│   ├── tasks/           # TODO/이슈 등록
│   ├── docs/            # 문서 링크/권한 (옵션)
│   ├── policies/        # 근무시간·휴일·권한·제한
│   └── utils/           # 타임존/ICS/헬스체크/멱등성
├── types/               # 공통 타입 정의
├── config/              # 설정 관리
├── utils/               # 공통 유틸리티
└── server.py            # MCP 서버 메인

命名空间详细信息

1.会议*

日程安排和会议管理

工具：

  • meetings.create -创建新会议
  • meetings.get -查看会议信息
  • meetings.update -修改会议
  • meetings.cancel -取消会议
  • meetings.list -查看会议列表
  • meetings.findSlots -搜索与会者的可用时间
  • meetings.getAvailability -查看用户可用性

2.房间*

会议室预订和管理

工具：

  • rooms.search -搜索会议室
  • rooms.get -查看会议室信息
  • rooms.getAvailability -查看会议室可用性
  • rooms.reserve -预订会议室
  • rooms.cancelReservation -取消预订
  • rooms.listReservations -预订列表
  • rooms.checkIn -入住会议室

3.邮寄*

电子邮件管理

工具：

  • mail.send -发送电子邮件
  • mail.createDraft -创建草稿
  • mail.updateDraft -修改草稿
  • mail.sendDraft -发送草稿
  • mail.get -查看电子邮件
  • mail.getThread -主题查询
  • mail.search -搜索电子邮件
  • mail.reply -回复
  • mail.forward -转发

4.目录*

用户和组目录

工具：

  • directory.searchUsers -搜索用户
  • directory.getUser -用户查询
  • directory.getUserByEmail -通过电子邮件查看用户
  • directory.getUserByEmployeeId -四次查看用户
  • directory.resolveIdentities - 身份规范化 （电子邮件/号码/别名→标准ID）
  • directory.searchGroups -搜索组
  • directory.getGroup -查看组
  • directory.getGroupMembers -查看组成员
  • directory.getOrgChart -查看组织图
  • directory.getDirectReports -直接负载查询

5.任务*

任务管理（Jira、Notion等适配器）

工具：

  • tasks.create -创建任务
  • tasks.get -查看任务
  • tasks.update -修改任务
  • tasks.delete -删除任务
  • tasks.search -搜索任务
  • tasks.addComment -添加评论
  • tasks.assign -指派任务

6.docs.*（可选）

文档管理

工具：

  • docs.search -搜索文档
  • docs.get -查询文档
  • docs.getPermissions -权限查询
  • docs.share -共享文档
  • docs.checkAccess -验证访问权限
  • docs.revokeAccess -取消访问权限

7.政策*

策略和限制

工具：

  • policies.getWorkingHours -查询工作时间
  • policies.listHolidays -假日列表
  • policies.isWorkingDay -确认工作日
  • policies.getRateLimits -查询请求限制
  • policies.checkRateLimit -确认请求限制
  • policies.getSpamPolicy -查看垃圾邮件策略
  • policies.checkPermission -验证权限
  • policies.getPermissions -用户权限列表

8.实用工具*

实用程序功能

工具：

  • utils.convertTimezone -时间区转换
  • utils.getTimezoneInfo -关于时区
  • utils.listTimezones -时间区列表
  • utils.generateICS -创建ICS文件
  • utils.parseICS -解析ICS文件
  • utils.healthCheck -健康检查
  • utils.generateIdempotencyKey -生成幂等密钥
  • utils.validateIdempotencyKey -验证幂等密钥

安装

# 의존성 설치
pip install -e .

# 개발 의존성 포함 설치
pip install -e ".[dev]"

设置

.env 创建文件以配置设置：

cp .env.example .env

主要设置项目：

# API 설정
CORP_API_BASE_URL=https://api.corp.internal
CORP_API_KEY=your_api_key_here
CORP_API_TIMEOUT=30

# 인증
AUTH_TYPE=oauth2  # or api_key, basic
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=

# 기능
ENABLE_SPAM_FILTER=true
ENABLE_RATE_LIMITING=true
MAX_REQUESTS_PER_MINUTE=60

# 로깅
LOG_LEVEL=INFO
LOG_FORMAT=json

执行

选择传输方式

此服务器支持两种通信方式：

  1. stdio（标准I/O）：MCP客户端与进程之间的通信
  2. 超文本传输协议：通过网络进行通信（FastMCP内置HTTP服务器）

.env 在文件中 TRANSPORT 可以选择设置。

HTTP模式（建议）

# .env 파일 설정
TRANSPORT=http
WS_HOST=0.0.0.0
WS_PORT=8765

# 서버 실행
python -m corp_collab_mcp.server

服务器 http://0.0.0.0:8765在中运行。

stdio模式

# .env 파일 설정
TRANSPORT=stdio

# 서버 실행
python -m corp_collab_mcp.server

通过FastMCP客户端进行测试

# 툴 목록 확인
python -m corp_collab_mcp.client list-tools

# 툴 호출
python -m corp_collab_mcp.client call-tool meetings.list_meetings \
  --args '{"user_id": "user123", "start": "2025-01-01", "end": "2025-01-31"}'

MCP客户端设置

使用HTTP时（Claude Desktop等）

{
  "mcpServers": {
    "corp-collab": {
      "url": "http://localhost:8765",
      "env": {
        "CORP_API_KEY": "your_key_here"
      }
    }
  }
}

使用stdio时

{
  "mcpServers": {
    "corp-collab": {
      "command": "python",
      "args": ["-m", "corp_collab_mcp.server"],
      "env": {
        "CORP_API_KEY": "your_key_here",
        "TRANSPORT": "stdio"
      }
    }
  }
}

开发

代码格式化

black src/
ruff check src/ --fix

类型检查

mypy src/

测试

pytest

实施指南

当前项目 螺旋结构仅配置。每个处理程序函数 NotImplementedError激发。

FastMCP使用方法

该项目使用FastMCP以简洁的代码实现MCP服务器：

# 기존 MCP SDK 방식 (복잡함)
@app.call_tool()
async def call_tool(name: str, arguments: Any) -> Any:
    # 수동으로 라우팅 로직 구현 필요
    if name == "meetings.create":
        return await create_meeting(**arguments)
    # ...

# FastMCP 방식 (간단함)
@mcp.tool()
async def create_meeting(params: CreateMeetingRequest) -> Meeting:
    """Create a new calendar event/meeting."""
    # Pydantic 모델이 자동으로 JSON Schema로 변환됨
    # 함수 시그니처와 docstring이 자동으로 툴 정의가 됨

实施顺序

  1. 实施认证 (config/settings.py)

    • 实现API密钥、OAuth等身份验证方法

  2. API客户端实现

    • 实现每个命名空间的实际API调用
    • httpx 或使用其他HTTP客户端

  3. 实施处理程序

    • namespaces/*/handlers.py 实现文件中的每个函数
    • 将API响应转换为类型模型
    • 使用Pydantic模型作为参数时，FastMCP将自动验证

  4. 验证策略

    • policies 实施命名空间的策略验证逻辑
    • 垃圾邮件过滤器、速率限制等

  5. 错误处理

    • 将每个API中的错误转换为适当的MCP错误
    • 实施重试逻辑

  6. 测试

    • 创建单位测试
    • 创建集成测试

可扩展性

添加新命名空间

  1. src/corp_collab_mcp/namespaces/ 在下面创建新目录
  2. types.py, handlers.py, __init__.py 创建文件
  3. server.py的 register_namespaces() 向函数添加工具注册

示例：

# server.py
def register_namespaces() -> None:
    from corp_collab_mcp.namespaces import new_namespace

    mcp.tool()(new_namespace.handlers.some_function)

添加新工具

FastMCP非常简单：

  1. 名称空间的 types.py在中定义Pydantic模型
  2. handlers.py在中实现async函数
  3. server.py在 mcp.tool() 注册为装饰师

示例：

# namespaces/meetings/types.py
class CreateMeetingRequest(BaseModel):
    title: str
    attendees: list[str]
    time_range: TimeRange

# namespaces/meetings/handlers.py
async def create_meeting(params: CreateMeetingRequest) -> Meeting:
    """Create a new calendar event/meeting."""
    # 구현...
    pass

# server.py
mcp.tool()(meetings.handlers.create_meeting)

FastMCP自动：

  • 将函数名转换为工具名（create_meeting）
  • 将Docstring用作工具提示
  • 将Pydantic模型转换为JSON Schema
  • 类型验证和转换处理

许可证

麻省理工学院

支持

如果出现问题，请注册问题。

相关 MCP