# permissions-query-MCP

**Repository Path**: Zherphy/permissions-query-mcp

## Basic Information

- **Project Name**: permissions-query-MCP
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-01-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Community Repository Permissions MCP Server

一个基于Model Context Protocol (MCP)的服务器，用于查询社区仓库的权限信息。该服务封装了对MagicAPI的访问，提供结构化的权限数据查询功能。

## 功能特性

- **权限查询**: 查询指定社区和仓库的权限信息
- **缓存支持**: 可配置的内存缓存，减少API调用
- **错误处理**: 完善的错误处理和重试机制
- **验证机制**: 严格的输入参数和响应数据验证
- **资源访问**: 支持通过URI访问权限资源
- **配置灵活**: 支持环境变量和配置文件

## 快速开始

### 安装

```bash
# 从源码安装
git clone <repository-url>
cd community-permissions-mcp
npm install
npm run build

# 全局安装
npm install -g community-permissions-mcp
```

### 运行

```bash
# 基本运行
community-permissions-mcp

# 使用自定义配置
MCP_API_ENDPOINT=https://magicapi.osinfra.cn \
MCP_CACHE_ENABLED=true \
community-permissions-mcp
```

### 配置

复制环境变量示例文件：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```bash
# API配置
MCP_API_ENDPOINT=https://magicapi.osinfra.cn
MCP_API_TIMEOUT=10000

# 缓存配置
MCP_CACHE_ENABLED=true
MCP_CACHE_TTL=300

# 日志配置
MCP_LOG_LEVEL=info
MCP_LOG_FORMAT=text
```

## 使用示例

### 通过MCP客户端查询

```json
{
  "method": "tools/call",
  "params": {
    "name": "query_repository_permissions",
    "arguments": {
      "community": "unifiedbus",
      "repository": "unifiedbus/resources"
    }
  }
}
```

### 响应示例

```json
{
  "success": true,
  "data": {
    "community": "unifiedbus",
    "repository": "unifiedbus/resources",
    "maintainers": ["zengchen1024", "gzbang", "georgecao"],
    "committers": ["zengchen1024", "georgecao", "gzbang"],
    "sigName": "infrastructure",
    "branchKeepers": [],
    "repoAdmins": [],
    "lastUpdated": "2026-01-27T12:00:00.000Z",
    "queryTime": 7
  },
  "metadata": {
    "cached": false,
    "source": "magicapi.osinfra.cn",
    "timestamp": "2026-01-27T12:00:00.000Z"
  }
}
```

### 通过资源URI访问

```
permission://unifiedbus/unifiedbus/resources
```

## 与Claude Desktop集成

1. 打开Claude Desktop设置
2. 进入"Developer"选项卡
3. 添加MCP服务器配置：

```json
{
  "mcpServers": {
    "community-permissions": {
      "command": "npx",
      "args": ["community-permissions-mcp"],
      "env": {
        "MCP_API_ENDPOINT": "https://magicapi.osinfra.cn"
      }
    }
  }
}
```

4. 重启Claude Desktop

## 开发

### 项目结构

```
src/
├── index.ts              # 主入口点
├── server.ts             # MCP服务器核心
├── config.ts             # 配置管理
├── api/                  # API客户端
│   └── client.ts
├── tools/                # MCP工具
│   └── query-permissions.ts
├── resources/            # MCP资源
│   └── permission-resource.ts
├── validation/           # 验证模块
│   └── validator.ts
├── cache/                # 缓存模块
│   └── manager.ts
└── utils/                # 工具类
    └── logger.ts
```

### 构建和测试

```bash
# 开发模式（监听文件变化）
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

# 类型检查
npm run type-check

# 代码格式化
npm run format

# 代码检查
npm run lint
```

## API参考

### 工具

#### `query_repository_permissions`

查询指定社区和仓库的权限信息。

**参数**:
- `community` (string, required): 社区名称，如 "unifiedbus"
- `repository` (string, required): 仓库名称，格式为 "社区/仓库"，如 "unifiedbus/resources"

**返回**: 结构化的权限信息

### 资源

#### `permission://{community}/{repository}`

通过URI访问权限资源。

**URI格式**: `permission://{community}/{repository}`

**内容类型**: `application/json`

## 配置选项

| 环境变量 | 默认值 | 描述 |
|---------|--------|------|
| `MCP_API_ENDPOINT` | `https://magicapi.osinfra.cn` | API端点 |
| `MCP_API_TIMEOUT` | `10000` | API请求超时（毫秒） |
| `MCP_CACHE_ENABLED` | `true` | 是否启用缓存 |
| `MCP_CACHE_TTL` | `300` | 缓存生存时间（秒） |
| `MCP_MAX_RETRIES` | `3` | 最大重试次数 |
| `MCP_RETRY_DELAY` | `1000` | 重试延迟（毫秒） |
| `MCP_LOG_LEVEL` | `info` | 日志级别（debug/info/warn/error） |
| `MCP_LOG_FORMAT` | `text` | 日志格式（text/json） |

## 错误处理

服务提供详细的错误信息，包括：

- **验证错误**: 参数格式不正确
- **网络错误**: API连接失败
- **API错误**: 上游API返回错误
- **数据错误**: 响应数据格式无效

错误响应格式：

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "参数验证失败",
    "details": {
      "community": ["社区名称不能为空"]
    }
  }
}
```

## 性能优化

- **缓存**: 默认启用5分钟缓存，减少API调用
- **重试**: 网络错误时自动重试
- **并发控制**: 限制并发请求数量
- **连接池**: HTTP连接复用

## 许可证

MIT

## 支持

如有问题或建议，请提交Issue或联系维护者。