MCP API Documentation System

MCP文档知识

提供方 namyoungpark-2

文档知识 stdio · 本地进程 Token 社区 / 第三方
查看接入方式

一个基于Django REST Framework ViewSet自动分析并生成OpenAPI 3.0规范API文档的全自动化系统,支持Swagger UI展示。

一句话选型结论

按资料字段整理

MCP API Documentation System 属于文档知识类 MCP 服务器,stdio · 本地进程,Token,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

API文档Python本地部署自动化生成DjangoOpenAPISwagger

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
python -m venv venv

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP API Documentation System当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方namyoungpark-2上游标注的维护方 namyoungpark-2
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

17.9 KB
来自项目仓库与上游目录的原文,未做删改

MCP API 문서 자동화 시스템

Django REST Framework ViewSet을 자동으로 분석하여 OpenAPI 3.0 스펙의 API 문서를 생성하는 완전 자동화 시스템입니다.

📋 목차

  • 프로젝트 개요
  • 시스템 아키텍처
  • 주요 기능
  • 기술 스택
  • 프로젝트 구조
  • 로컬 환경 설정
  • 실행 방법
  • API 사용법
  • 구현 상세 내용
  • 테스트 방법
  • 생성된 API 문서 예시
  • 트러블슈팅

🎯 프로젝트 개요

목적

  • Django 프로젝트의 ViewSet을 자동으로 탐지하고 분석
  • 실제 serializer 필드를 기반으로 정확한 OpenAPI 3.0 스펙 생성
  • Request/Response 파라미터, 헤더, 바디 정보 완전 자동화
  • Swagger UI를 통한 직관적인 API 문서 제공

핵심 특징

  • ✅ 완전 자동화: 수동 설정 없이 ViewSet 자동 탐지
  • ✅ 정확한 스키마: 실제 serializer 필드 1:1 반영
  • ✅ 125개 엔드포인트: 모든 ViewSet CRUD 작업 지원
  • ✅ 실시간 생성: 코드 변경 시 즉시 문서 업데이트
  • ✅ JavaScript 호환: Swagger UI 완벽 지원

🏗️ 시스템 아키텍처```

┌─────────────────┐ HTTP Request ┌─────────────────┐
│ MCP Server │ ──────────────────► │ Python Parser │
│ (Spring Boot) │ │ (FastAPI) │
│ Port: 8080 │ │ Port: 8009 │
└─────────────────┘ └─────────────────┘
│ │
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Swagger UI │ │ Django Project │
│ API Docs HTML │ │ ViewSet Files │
│ /api-docs/html │ │ /shared_repos/ │
└─────────────────┘ └─────────────────┘


### 컴포넌트 설명

1. **Python Parser (FastAPI)**

   - Django ViewSet 자동 탐지 및 분석
   - OpenAPI 3.0 스펙 생성
   - 실제 serializer 필드 추출

2. **MCP Server (Spring Boot)**

   - Swagger UI 제공
   - JSON API 문서 서빙
   - 프록시 역할

3. **Django Project**
   - 분석 대상 ViewSet 파일들
   - 실제 serializer 정의

## 🚀 주요 기능

### 1. ViewSet 자동 탐지

- `app/` 디렉토리 내 모든 앱 스캔
- `views.py` 또는 `views/` 폴더 내 파일 분석
- `class \w+ViewSet` 패턴 자동 발견

### 2. Serializer 필드 추출

- `serializer_class` 속성 자동 감지
- 실제 필드 타입, nullable, required 정보 추출
- 중첩 serializer 지원

### 3. OpenAPI 3.0 스펙 생성

- Request 파라미터 (쿼리, 헤더, 바디)
- Response 스키마 (상태 코드별)
- 인증 정보 (Authorization 헤더)
- Pagination, Search, Filtering 지원

### 4. CRUD 엔드포인트 자동 생성

- **GET** `/api/v1/{resource}/` - 목록 조회
- **POST** `/api/v1/{resource}/` - 생성
- **GET** `/api/v1/{resource}/{id}/` - 상세 조회
- **PUT** `/api/v1/{resource}/{id}/` - 수정
- **DELETE** `/api/v1/{resource}/{id}/` - 삭제

## 🛠️ 기술 스택

### Backend

- **Python 3.12.2**: 메인 파싱 로직
- **FastAPI**: Python Parser 서버
- **Django**: 분석 대상 프로젝트
- **Django REST Framework**: ViewSet 분석

### Frontend

- **Spring Boot**: MCP 서버
- **Swagger UI**: API 문서 인터페이스
- **Thymeleaf**: HTML 템플릿

### 개발 도구

- **Gradle**: Spring Boot 빌드
- **uvicorn**: FastAPI 서버
- **watchfiles**: 자동 리로드

## 📁 프로젝트 구조```
mcp-docs-server-final/
├── python-parser/                    # Python Parser 서버
│   ├── main.py                      # FastAPI 서버 진입점
│   ├── src/
│   │   ├── application/             # 애플리케이션 레이어
│   │   │   └── use_cases/
│   │   │       └── generate_api_docs_use_case.py
│   │   ├── domain/                  # 도메인 레이어
│   │   │   └── entities/
│   │   │       ├── api_documentation.py
│   │   │       ├── api_endpoint.py
│   │   │       └── api_parameter.py
│   │   ├── infrastructure/          # 인프라 레이어
│   │   │   ├── generators/
│   │   │   │   └── api_documentation_generator.py
│   │   │   └── parsers/
│   │   │       └── python_parser.py
│   │   └── presentation/            # 프레젠테이션 레이어
│   │       └── controllers/
│   │           └── api_docs_controller.py
│   ├── generated_docs/              # 생성된 API 문서
│   │   └── ucms-be_api_docs.json
│   └── requirements.txt
├── shared_repos/                    # 분석 대상 Django 프로젝트
│   └── ucms-be/
│       └── app/
│           ├── account/
│           ├── revenue/
│           ├── content/
│           └── ... (기타 앱들)
├── src/                             # Spring Boot MCP 서버
│   └── main/
│       ├── java/
│       │   └── com/odk/
│       │       └── controller/
│       │           └── ApiDocsController.java
│       └── resources/
│           ├── templates/
│           │   └── swagger-viewer.html
│           └── static/
│               └── openapi/
├── build.gradle                     # Spring Boot 빌드 설정
└── docker-compose.override.yml      # Docker 설정

🔧 로컬 환경 설정

1. Python 환경 설정```bash

Python 3.12.2 설치 (pyenv 사용)

pyenv install 3.12.2
pyenv local 3.12.2

가상환경 생성 및 활성화

cd python-parser
python -m venv venv
source venv/bin/activate # macOS/Linux

또는

venv\Scripts\activate # Windows


### 2. Python 의존성 설치```bash
cd python-parser
pip install -r requirements.txt

3. Spring Boot 환경 설정```bash

Java 17 이상 필요

java -version

Gradle 빌드

./gradlew build


## 🚀 실행 방법

### 1. Python Parser 서버 시작```bash
cd python-parser
python main.py

서버 정보:

  • URL: http://localhost:8009
  • 자동 리로드: 활성화
  • Django 환경: 자동 설정

2. Spring Boot MCP 서버 시작```bash

프로젝트 루트에서

./gradlew bootRun


**서버 정보:**

- URL: `http://localhost:8080`
- Swagger UI: `http://localhost:8080/api-docs/html`
- JSON API: `http://localhost:8080/api-docs/json`

### 3. API 문서 생성```bash
# Python Parser 서버가 실행 중인 상태에서
curl -X POST "http://localhost:8009/api/v1/docs/generate/ucms-be?base_url=http://localhost:8009&save_to_file=true"

📖 API 사용법

1. API 문서 생성 엔드포인트```http

POST /api/v1/docs/generate/{project_name}


**파라미터:**

- `project_name`: 프로젝트 이름 (예: ucms-be)
- `base_url`: 기본 URL (예: http://localhost:8009)
- `save_to_file`: 파일 저장 여부 (true/false)

**응답:**```json
{
  "success": true,
  "message": "API documentation generated successfully",
  "data": {
    "endpoints_count": 125,
    "file_path": "generated_docs/ucms-be_api_docs.json"
  }
}

2. 생성된 문서 확인

  • Swagger UI: http://localhost:8080/api-docs/html
  • JSON 파일: http://localhost:8080/api-docs/json
  • 로컬 파일: python-parser/generated_docs/ucms-be_api_docs.json

🔍 구현 상세 내용

1. ViewSet 자동 탐지 로직```python

def discover_viewsets(django_app_path: str) -> List[Tuple[str, str]]:
"""
Django 앱 디렉토리에서 ViewSet 클래스 자동 탐지

Args:
    django_app_path: Django 앱 경로

Returns:
    List[Tuple[앱명.ViewSet명, URL경로]]
"""
viewsets = []

# app/ 디렉토리 내 모든 앱 스캔
for app_dir in os.listdir(django_app_path):
    app_path = os.path.join(django_app_path, app_dir)

    if os.path.isdir(app_path):
        # views.py 파일 확인
        views_file = os.path.join(app_path, "views.py")
        if os.path.exists(views_file):
            viewsets.extend(extract_viewsets_from_file(views_file, app_dir))

        # views/ 폴더 확인
        views_dir = os.path.join(app_path, "views")
        if os.path.isdir(views_dir):
            for file in os.listdir(views_dir):
                if file.endswith(".py"):
                    file_path = os.path.join(views_dir, file)
                    viewsets.extend(extract_viewsets_from_file(file_path, f"{app_dir}/views/{file[:-3]}"))

return viewsets

### 2. Serializer 필드 추출 로직```python
def extract_serializer_from_viewset(viewset_class, viewset_name: str) -> Dict[str, Any]:
    """
    ViewSet에서 실제 사용하는 serializer 필드 추출

    Args:
        viewset_class: ViewSet 클래스
        viewset_name: ViewSet 이름

    Returns:
        Dict[str, Any]: 필드 정보 딕셔너리
    """
    try:
        # 1. serializer_class 속성 확인
        if hasattr(viewset_class, 'serializer_class'):
            serializer_class = viewset_class.serializer_class
            return extract_serializer_fields(serializer_class)

        # 2. get_serializer_class 메서드 확인
        if hasattr(viewset_class, 'get_serializer_class'):
            serializer_class = viewset_class.get_serializer_class()
            return extract_serializer_fields(serializer_class)

        # 3. 소스 코드 분석으로 serializer 패턴 찾기
        return extract_serializer_from_source(viewset_class, viewset_name)

    except Exception as e:
        print(f"[문서 자동화] {viewset_name}에서 serializer 필드 추출 실패: {e}")
        return None

3. OpenAPI 스펙 생성 로직```python

def generate_openapi_for_viewset(
viewset_name: str,
file_path: str,
base_url: str,
model_name: str = None,
) -> List[ApiEndpoint]:
"""
ViewSet에서 OpenAPI 엔드포인트 생성

Args:
    viewset_name: ViewSet 클래스명
    file_path: ViewSet 파일 경로
    base_url: 기본 URL
    model_name: 모델명 (선택사항)

Returns:
    List[ApiEndpoint]: 생성된 엔드포인트 목록
"""
# 1. ViewSet 클래스 import
viewset_class = import_viewset_class(file_path, viewset_name)

# 2. Serializer 필드 추출
serializer_fields = extract_serializer_from_viewset(viewset_class, viewset_name)

# 3. URL 경로 생성
resource_name = model_name or viewset_name.replace('ViewSet', '').lower()
base_path = f"/api/v1/{resource_name}/"

# 4. CRUD 엔드포인트 생성
endpoints = []

# GET /api/v1/{resource}/ - 목록 조회
endpoints.append(ApiEndpoint(
    path=base_path,
    method=HttpMethod.GET,
    summary=f"Get {resource_name} list",
    description=f"Retrieve a list of {resource_name}",
    parameters=generate_list_parameters(),
    responses=generate_list_responses(serializer_fields)
))

# POST /api/v1/{resource}/ - 생성
endpoints.append(ApiEndpoint(
    path=base_path,
    method=HttpMethod.POST,
    summary=f"Create {resource_name}",
    description=f"Create a new {resource_name}",
    parameters=generate_create_parameters(),
    request_body=generate_request_body(serializer_fields),
    responses=generate_create_responses(serializer_fields)
))

# 기타 CRUD 엔드포인트들...

return endpoints

## 🧪 테스트 방법

### 1. 단위 테스트```bash
cd python-parser
python -m pytest tests/

2. 통합 테스트```bash

1. Python Parser 서버 시작

cd python-parser
python main.py

2. API 문서 생성 요청

curl -X POST "http://localhost:8009/api/v1/docs/generate/ucms-be?base_url=http://localhost:8009&save_to_file=true"

3. 생성된 파일 확인

ls -la generated_docs/
cat generated_docs/ucms-be_api_docs.json | jq '.paths | keys | length'


### 3. Swagger UI 테스트```bash
# 1. Spring Boot 서버 시작
./gradlew bootRun

# 2. 브라우저에서 확인
open http://localhost:8080/api-docs/html

4. 엔드포인트별 테스트```bash

Revenue API 테스트

curl -X GET "http://localhost:8080/api-docs/json" | jq '.paths | keys | grep revenue'

AdminUser API 테스트

curl -X GET "http://localhost:8080/api-docs/json" | jq '.paths | keys | grep adminuser'


## 📊 생성된 API 문서 예시

### 1. Revenue API 엔드포인트```json
{
  "/api/v1/revenues/": {
    "get": {
      "summary": "Get revenues list",
      "description": "Retrieve a list of revenues",
      "tags": ["revenue"],
      "parameters": [
        {
          "name": "Authorization",
          "in": "header",
          "required": true,
          "description": "Bearer token for authentication",
          "schema": { "type": "string" }
        },
        {
          "name": "page",
          "in": "query",
          "required": false,
          "description": "Page number for pagination",
          "schema": { "type": "integer" }
        }
      ],
      "responses": {
        "200": {
          "description": "Successful response",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": { "type": "integer" },
                  "amount": { "type": "number", "format": "decimal" },
                  "currency": { "type": "string" },
                  "created_at": { "type": "string", "format": "date-time" },
                  "updated_at": { "type": "string", "format": "date-time" }
                }
              }
            }
          }
        }
      }
    }
  }
}

2. 생성된 엔드포인트 통계

  • 총 엔드포인트: 125개
  • ViewSet 개수: 25개
  • 주요 ViewSet:
  • Revenue (16개 필드)
  • RevenueShare (16개 필드)
  • AdminUser (8개 필드)
  • UserActionHistory (12개 필드)
  • VideoSource (23개 필드)
  • Series (18개 필드)
  • Content (다양한 필드)
  • 기타 모든 ViewSet

🔧 트러블슈팅

1. Django 환경 설정 문제

문제: DJANGO_SETTINGS_MODULE 미설정```bash
Error: No module named 'django'


**해결책**:```python
def setup_django_environment(django_app_path: str):
    """Django 환경 설정"""
    import os
    import sys
    import django

    # Django 설정 모듈 환경변수 설정
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'app.settings')

    # 프로젝트 및 앱 경로를 Python 경로에 추가
    project_root = os.path.dirname(django_app_path)
    sys.path.insert(0, project_root)
    sys.path.insert(0, django_app_path)

    # Django 설정
    django.setup()

2. ViewSet Import 실패

문제: 상대 import 오류```bash
Error: attempted relative import with no known parent package


**해결책**:```python
def import_viewset_class(file_path: str, viewset_name: str):
    """ViewSet 클래스 import"""
    try:
        # 1. 직접 import 시도
        module_name = get_module_name_from_path(file_path)
        module = importlib.import_module(module_name)
        return getattr(module, viewset_name)
    except ImportError:
        # 2. fallback: 파일 파싱
        return parse_viewset_from_file(file_path, viewset_name)

3. Serializer 필드 추출 실패

문제: cached_property 오류```bash
Error: 'cached_property' object has no attribute 'get_fields'


**해결책**:```python
def extract_serializer_fields(serializer_class):
    """Serializer 필드 추출"""
    try:
        # Serializer 인스턴스 생성
        serializer = serializer_class()

        # fields 속성에 안전하게 접근
        if hasattr(serializer, 'fields'):
            fields = serializer.fields
            return {name: extract_field_schema(field) for name, field in fields.items()}
    except Exception as e:
        print(f"Serializer 필드 추출 실패: {e}")
        return None

4. JavaScript 호환성 문제

문제: Swagger UI에서 Object.keys() 오류```javascript
TypeError: Cannot convert undefined or null to object


**해결책**:```python
def to_openapi_dict(self) -> Dict[str, Any]:
    """OpenAPI 3.0 형식으로 변환"""
    endpoint_dict = {
        "summary": endpoint.summary,
        "description": endpoint.description,
        "tags": endpoint.tags,
        "deprecated": endpoint.deprecated,
        "parameters": [...],
    }

    # null 값 제거로 JavaScript 호환성 확보
    if endpoint.request_body is not None:
        endpoint_dict["requestBody"] = endpoint.request_body

    if endpoint.responses is not None:
        endpoint_dict["responses"] = endpoint.responses

    return endpoint_dict

📈 성능 최적화

1. 캐싱 전략

  • ViewSet 클래스 import 결과 캐싱
  • Serializer 필드 추출 결과 캐싱
  • 파일 변경 감지로 부분 업데이트

2. 병렬 처리

  • 여러 ViewSet 동시 분석
  • 파일 I/O 비동기 처리

3. 메모리 최적화

  • 불필요한 객체 생성 방지
  • 가비지 컬렉션 최적화

🔮 향후 개선 계획

1. 기능 확장

  • [ ] GraphQL 스키마 생성 지원
  • [ ] API 버전 관리
  • [ ] 커스텀 필터링/정렬 지원
  • [ ] API 테스트 코드 자동 생성

2. 성능 개선

  • [ ] Redis 캐싱 도입
  • [ ] 배치 처리 최적화
  • [ ] 메모리 사용량 모니터링

3. 사용성 개선

  • [ ] 웹 인터페이스 추가
  • [ ] 실시간 문서 업데이트
  • [ ] API 문서 버전 관리

📞 지원 및 문의

프로젝트 관련 문의사항이나 버그 리포트는 이슈를 통해 제출해 주세요.


개발자: AI Assistant
최종 업데이트: 2024년 12월
버전: 1.0.0

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
MCP API Documentation System 怎么安装?

在客户端按下面的安装命令接入:python -m venv venv。装完在客户端配置里引用同一个包或端点。

MCP API Documentation System 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

MCP API Documentation System 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

MCP API Documentation System 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

MCP API Documentation System 能提供哪些能力?

资料显示能力标签包括 API文档、API集成、Python。具体工具清单以官方文档为准。

MCP API Documentation System 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

MCP API Documentation System 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。