drophtml-mcp 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/NOTICE +6 -0
- package/README.md +150 -0
- package/dist/app.js +300 -0
- package/dist/server.js +7 -0
- package/package.json +42 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 drophtml.app
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/NOTICE
ADDED
package/README.md
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# drophtml-mcp
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/drophtml-mcp)
|
|
4
|
+
[](https://nodejs.org)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
|
|
7
|
+
**[DropHTML](https://drophtml.app)를 MCP 도구로 노출하는 서버.** MCP를 지원하는 에이전트·IDE에
|
|
8
|
+
등록하면 AI가 HTML·마크다운 페이지를 **게시·검색·조회·편집·삭제**하고 공유 링크
|
|
9
|
+
(`{slug}.drophtml.app`)를 바로 받습니다.
|
|
10
|
+
|
|
11
|
+
## MCP란, 이 서버는 무엇인가
|
|
12
|
+
|
|
13
|
+
**MCP(Model Context Protocol)** 는 AI 에이전트가 외부 도구를 표준 방식으로 호출하게 하는 오픈
|
|
14
|
+
프로토콜입니다. MCP를 지원하는 클라이언트에 `drophtml-mcp`를 등록하면, AI가 아래 도구로 DropHTML
|
|
15
|
+
페이지를 게시·관리할 수 있습니다.
|
|
16
|
+
|
|
17
|
+
- **설치 불필요** — `npx -y drophtml-mcp` 한 줄로 실행됩니다.
|
|
18
|
+
- **바로 운영 서버 사용** — 별도 설정 없이 `https://drophtml.app`에 게시됩니다.
|
|
19
|
+
|
|
20
|
+
### 제공 도구
|
|
21
|
+
|
|
22
|
+
등록하면 AI가 다음 도구를 쓸 수 있습니다(상세 설명·스키마는 연결 시 클라이언트가 자동으로 표시):
|
|
23
|
+
|
|
24
|
+
- **`create_share`** — 새 HTML·마크다운 글 게시(공유 링크·관리 토큰 반환)
|
|
25
|
+
- **`update_share` / `delete_share`** — 게시글 편집·삭제(작성자 관리 토큰 필요)
|
|
26
|
+
- **`search_shares` / `get_share`** — 글 검색·조회
|
|
27
|
+
- **`get_daily_views` / `popular_tags` / `site_stats`** — 조회수·인기 태그·사이트 통계
|
|
28
|
+
|
|
29
|
+
### 공개 범위
|
|
30
|
+
|
|
31
|
+
게시할 때 `visibility`로 노출 범위를 정합니다(미지정 시 기본 `public`).
|
|
32
|
+
|
|
33
|
+
- **`public`** (기본) — 홈·검색·태그 목록에 노출되고, `search_shares`로도 검색됩니다.
|
|
34
|
+
- **`unlisted`** — 목록·검색에 뜨지 않고, 링크(`{slug}.drophtml.app`)를 아는 사람만 볼 수 있습니다.
|
|
35
|
+
- **비밀번호** — `password`를 지정하면 열람 시 비밀번호가 필요하며, **자동으로 `unlisted`로 전환**됩니다.
|
|
36
|
+
|
|
37
|
+
에이전트에게 "**unlisted로 올려줘**", "**비밀번호 걸어서 게시해줘**"처럼 말하면 됩니다.
|
|
38
|
+
|
|
39
|
+
## 클라이언트 등록
|
|
40
|
+
|
|
41
|
+
모든 클라이언트는 **같은 stdio 명령**을 실행하도록 설정합니다 — `command: npx`, `args: ["-y", "drophtml-mcp"]`.
|
|
42
|
+
별도 설정 없이 운영 서버(`drophtml.app`)에 연결됩니다.
|
|
43
|
+
|
|
44
|
+
### 에이전트
|
|
45
|
+
|
|
46
|
+
#### Claude Code (CLI)
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
claude mcp add drophtml -- npx -y drophtml-mcp
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
등록 후 **새 세션으로 재시작**하면 도구가 보입니다.
|
|
53
|
+
|
|
54
|
+
#### Claude Desktop
|
|
55
|
+
|
|
56
|
+
설정 파일 `claude_desktop_config.json`에 추가합니다.
|
|
57
|
+
(macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`)
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{
|
|
61
|
+
"mcpServers": {
|
|
62
|
+
"drophtml": {
|
|
63
|
+
"command": "npx",
|
|
64
|
+
"args": ["-y", "drophtml-mcp"]
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### IDE
|
|
71
|
+
|
|
72
|
+
#### Cursor
|
|
73
|
+
|
|
74
|
+
`~/.cursor/mcp.json`(전역) 또는 프로젝트의 `.cursor/mcp.json`에 추가합니다
|
|
75
|
+
(Settings → MCP → *Add new MCP server*로도 가능).
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"mcpServers": {
|
|
80
|
+
"drophtml": {
|
|
81
|
+
"command": "npx",
|
|
82
|
+
"args": ["-y", "drophtml-mcp"]
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
#### VS Code (GitHub Copilot)
|
|
89
|
+
|
|
90
|
+
워크스페이스의 `.vscode/mcp.json`에 추가합니다(명령 팔레트 *MCP: Add Server*로도 가능).
|
|
91
|
+
VS Code는 최상위 키가 `servers`이고 `type`을 명시합니다:
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
{
|
|
95
|
+
"servers": {
|
|
96
|
+
"drophtml": {
|
|
97
|
+
"type": "stdio",
|
|
98
|
+
"command": "npx",
|
|
99
|
+
"args": ["-y", "drophtml-mcp"]
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
#### Windsurf
|
|
106
|
+
|
|
107
|
+
Settings → Cascade → MCP, 또는 `~/.codeium/windsurf/mcp_config.json`에 추가합니다:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"mcpServers": {
|
|
112
|
+
"drophtml": {
|
|
113
|
+
"command": "npx",
|
|
114
|
+
"args": ["-y", "drophtml-mcp"]
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
#### 기타 클라이언트 (Cline · Zed · JetBrains AI Assistant 등)
|
|
121
|
+
|
|
122
|
+
`command`/`args` 기반 stdio 서버를 받는 클라이언트라면 동일하게 `npx -y drophtml-mcp`를 실행하도록
|
|
123
|
+
설정하면 됩니다.
|
|
124
|
+
|
|
125
|
+
## 사용 예
|
|
126
|
+
|
|
127
|
+
등록 후에는 에이전트에게 자연어로 지시하면 됩니다 — 도구 호출은 AI가 알아서 합니다.
|
|
128
|
+
|
|
129
|
+
- "이 HTML을 DropHTML에 올리고 공유 링크 줘" → `create_share`
|
|
130
|
+
- "이 마크다운을 `mcp`, `docs` 태그 달아서 **unlisted**로 게시해줘" → `create_share`
|
|
131
|
+
- "방금 올린 글 제목을 '릴리스 노트'로 바꿔줘" → `update_share`
|
|
132
|
+
- "그 글 삭제해줘" → `delete_share`
|
|
133
|
+
- "`mcp` 태그로 검색해서 최근 글 보여줘" → `search_shares`
|
|
134
|
+
- "이 글 최근 조회수 추이 알려줘" → `get_daily_views`
|
|
135
|
+
- "지금 인기 태그랑 사이트 전체 통계 요약해줘" → `popular_tags` + `site_stats`
|
|
136
|
+
|
|
137
|
+
> 편집·삭제(`update_share`/`delete_share`)는 게시 때 발급된 **관리 토큰**이 있어야 합니다. 보통은
|
|
138
|
+
> 앞선 `create_share` 결과를 대화 맥락에 두면 에이전트가 토큰을 이어서 사용합니다.
|
|
139
|
+
|
|
140
|
+
## 요구사항
|
|
141
|
+
|
|
142
|
+
- Node.js **18 이상** (글로벌 `fetch`·`AbortController` 사용)
|
|
143
|
+
|
|
144
|
+
## 라이선스
|
|
145
|
+
|
|
146
|
+
[Apache-2.0](./LICENSE) — Copyright 2026 drophtml.app.
|
|
147
|
+
|
|
148
|
+
## 링크
|
|
149
|
+
|
|
150
|
+
- 홈페이지: <https://drophtml.app>
|
package/dist/app.js
ADDED
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* DropHTML MCP 서버 — DropHTML REST API를 MCP 도구로 노출하는 얇은 어댑터(TypeScript).
|
|
3
|
+
*
|
|
4
|
+
* 설계(B안): 새 도메인 로직 없음. 각 도구는 DropHTML의 기존 엔드포인트
|
|
5
|
+
* (POST/GET/DELETE/PUT /api/shares*, /raw/{slug}, /api/tags, /api/stats)를 그대로 호출한다.
|
|
6
|
+
* 검증·2MB 상한·레이트리밋·토큰 검사는 전부 DropHTML 서버가 담당한다.
|
|
7
|
+
* (유일한 예외: update_share — 서버 PUT이 full-replace라, 미지정 필드 리셋을 막기 위해
|
|
8
|
+
* 현재 값을 manage API로 읽어 병합한다. 아래 update_share 주석 참고.)
|
|
9
|
+
*
|
|
10
|
+
* bin 진입점은 server.ts(이 파일은 테스트가 main 실행 없이 import 할 수 있게 분리).
|
|
11
|
+
*
|
|
12
|
+
* 환경변수
|
|
13
|
+
* DROPHTML_BASE_URL 대상 DropHTML 인스턴스 (기본 https://drophtml.app; 로컬 개발 시 http://127.0.0.1:8000 로 덮어씀)
|
|
14
|
+
* DROPHTML_ADMIN_TOKEN (선택) 운영자 삭제/모더레이션용 ADMIN_TOKEN
|
|
15
|
+
* DROPHTML_TIMEOUT (선택) 요청 타임아웃 초 (기본 30; 숫자가 아니거나 0 이하면 30으로 폴백)
|
|
16
|
+
* DROPHTML_MCP_TRANSPORT stdio | streamable-http (기본 stdio)
|
|
17
|
+
* DROPHTML_MCP_HOST http transport 바인드 호스트 (기본 127.0.0.1)
|
|
18
|
+
* DROPHTML_MCP_PORT http transport 포트 (기본 8765)
|
|
19
|
+
*/
|
|
20
|
+
import { createServer as createHttpServer } from "node:http";
|
|
21
|
+
import { createRequire } from "node:module";
|
|
22
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
23
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
24
|
+
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
|
|
25
|
+
import { z } from "zod";
|
|
26
|
+
// --- 설정 (환경변수) --------------------------------------------------------
|
|
27
|
+
// 이 MCP 서버는 DropHTML 전용이라 기본 대상은 운영 도메인. 로컬 개발 시에만
|
|
28
|
+
// DROPHTML_BASE_URL=http://127.0.0.1:8000 으로 덮어쓴다.
|
|
29
|
+
const BASE_URL = (process.env.DROPHTML_BASE_URL ?? "https://drophtml.app").replace(/\/+$/, "");
|
|
30
|
+
const ADMIN_TOKEN = process.env.DROPHTML_ADMIN_TOKEN;
|
|
31
|
+
// 잘못된 값(NaN·0 이하)은 30초로 폴백 — setTimeout(fn, NaN)은 0ms 로 동작해
|
|
32
|
+
// 모든 요청이 즉시 abort 되는 사고를 막는다.
|
|
33
|
+
const _rawTimeout = Number(process.env.DROPHTML_TIMEOUT ?? "30");
|
|
34
|
+
const TIMEOUT_SECONDS = Number.isFinite(_rawTimeout) && _rawTimeout > 0 ? _rawTimeout : 30;
|
|
35
|
+
const TIMEOUT_MS = TIMEOUT_SECONDS * 1000;
|
|
36
|
+
// 버전은 package.json 이 단일 소스다(dist/app.js 기준 ../package.json —
|
|
37
|
+
// npm 배포물에도 package.json 은 항상 포함되므로 어디서든 존재한다).
|
|
38
|
+
const PKG_VERSION = createRequire(import.meta.url)("../package.json").version;
|
|
39
|
+
function errMsg(e) {
|
|
40
|
+
return e instanceof Error ? e.message : String(e);
|
|
41
|
+
}
|
|
42
|
+
/** DropHTML 로 fetch 한다(타임아웃·네트워크 오류를 명확한 메시지로 매핑, 상태코드 검사는 호출부 몫). */
|
|
43
|
+
async function doFetch(method, path, opts = {}) {
|
|
44
|
+
const url = new URL(BASE_URL + path);
|
|
45
|
+
for (const [k, v] of Object.entries(opts.query ?? {})) {
|
|
46
|
+
if (v !== undefined && v !== null)
|
|
47
|
+
url.searchParams.set(k, String(v));
|
|
48
|
+
}
|
|
49
|
+
const hasBody = opts.body !== undefined;
|
|
50
|
+
const controller = new AbortController();
|
|
51
|
+
const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
|
|
52
|
+
try {
|
|
53
|
+
return await fetch(url, {
|
|
54
|
+
method,
|
|
55
|
+
headers: {
|
|
56
|
+
...(hasBody ? { "content-type": "application/json" } : {}),
|
|
57
|
+
...(opts.headers ?? {}),
|
|
58
|
+
},
|
|
59
|
+
body: hasBody ? JSON.stringify(opts.body) : undefined,
|
|
60
|
+
signal: controller.signal,
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
catch (e) {
|
|
64
|
+
// 타임아웃 abort 는 DOMException(name=AbortError)이라 instanceof Error 로 못 거른다.
|
|
65
|
+
if (e?.name === "AbortError") {
|
|
66
|
+
throw new Error(`DropHTML API ${method} ${path} → timed out after ${TIMEOUT_SECONDS}s`);
|
|
67
|
+
}
|
|
68
|
+
const cause = e?.cause?.message;
|
|
69
|
+
throw new Error(`DropHTML API ${method} ${path} → ${errMsg(e)}${cause ? ` (${cause})` : ""}`);
|
|
70
|
+
}
|
|
71
|
+
finally {
|
|
72
|
+
clearTimeout(timer);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/** 오류 응답 본문에서 사람이 읽을 detail 을 뽑는다. HTML 본문(커스텀 404 페이지 등)은 상태 문구로 요약. */
|
|
76
|
+
function extractDetail(text, resp) {
|
|
77
|
+
try {
|
|
78
|
+
const j = JSON.parse(text);
|
|
79
|
+
if (j && typeof j === "object" && "detail" in j)
|
|
80
|
+
return String(j.detail);
|
|
81
|
+
}
|
|
82
|
+
catch {
|
|
83
|
+
/* 비 JSON 응답 */
|
|
84
|
+
}
|
|
85
|
+
const t = text.trim();
|
|
86
|
+
if (t.startsWith("<"))
|
|
87
|
+
return resp.statusText || "HTML error page";
|
|
88
|
+
return t.slice(0, 200);
|
|
89
|
+
}
|
|
90
|
+
/** DropHTML REST 호출. 2xx면 JSON(또는 텍스트) 반환, 4xx/5xx면 명확한 예외. */
|
|
91
|
+
async function apiRequest(method, path, opts = {}) {
|
|
92
|
+
const resp = await doFetch(method, path, opts);
|
|
93
|
+
const text = await resp.text();
|
|
94
|
+
if (!resp.ok) {
|
|
95
|
+
throw new Error(`DropHTML API ${method} ${path} → ${resp.status}: ${extractDetail(text, resp)}`);
|
|
96
|
+
}
|
|
97
|
+
const ct = resp.headers.get("content-type") ?? "";
|
|
98
|
+
return ct.includes("application/json") ? JSON.parse(text) : text;
|
|
99
|
+
}
|
|
100
|
+
function registerTool(server, name, description, shape, run, annotations) {
|
|
101
|
+
server.registerTool(name, { description, inputSchema: shape, annotations }, async (args) => {
|
|
102
|
+
try {
|
|
103
|
+
const data = await run(args);
|
|
104
|
+
const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
|
|
105
|
+
return { content: [{ type: "text", text }] };
|
|
106
|
+
}
|
|
107
|
+
catch (e) {
|
|
108
|
+
return { content: [{ type: "text", text: errMsg(e) }], isError: true };
|
|
109
|
+
}
|
|
110
|
+
});
|
|
111
|
+
}
|
|
112
|
+
// 공유글 생성/편집이 공유하는 입력 스키마 (편집은 content 를 optional 로 완화해 재사용).
|
|
113
|
+
// create 는 미지정 필드를 본문에서 빼서 DropHTML 서버의 기본값(ShareIn)이 단일 진실 소스가
|
|
114
|
+
// 되게 한다. update 는 PUT 이 full-replace 라 같은 전략이면 미지정 필드가 리셋된다 —
|
|
115
|
+
// update_share 도구가 현재 값을 먼저 읽어 병합한다(해당 도구 주석 참고).
|
|
116
|
+
const shareFields = {
|
|
117
|
+
content: z.string().describe("Page source: HTML markup, or raw Markdown if content_type='markdown'. Max 2MB."),
|
|
118
|
+
title: z.string().optional().describe("Optional title (search, OG card, tab title)."),
|
|
119
|
+
tags: z.array(z.string()).optional().describe("Optional tags for discovery."),
|
|
120
|
+
content_type: z.enum(["html", "markdown"]).optional().describe("'html' (default) or 'markdown'."),
|
|
121
|
+
visibility: z.enum(["public", "unlisted"]).optional().describe("'public' (default) or 'unlisted'. A password forces unlisted."),
|
|
122
|
+
password: z.string().optional().describe("Optional password to gate the page."),
|
|
123
|
+
};
|
|
124
|
+
function buildShareBody(a) {
|
|
125
|
+
const body = { content: a.content };
|
|
126
|
+
if (a.title !== undefined)
|
|
127
|
+
body.title = a.title;
|
|
128
|
+
if (a.tags !== undefined)
|
|
129
|
+
body.tags = a.tags;
|
|
130
|
+
if (a.content_type !== undefined)
|
|
131
|
+
body.content_type = a.content_type;
|
|
132
|
+
if (a.visibility !== undefined)
|
|
133
|
+
body.visibility = a.visibility;
|
|
134
|
+
if (a.password)
|
|
135
|
+
body.password = a.password;
|
|
136
|
+
return body;
|
|
137
|
+
}
|
|
138
|
+
// --- 서버 팩토리 (stdio는 1회, HTTP 무상태는 요청마다 새로 생성) -------------
|
|
139
|
+
export function buildServer() {
|
|
140
|
+
const server = new McpServer({ name: "DropHTML", version: PKG_VERSION });
|
|
141
|
+
// 쓰기
|
|
142
|
+
registerTool(server, "create_share", "Publish a new HTML or Markdown page to DropHTML and get a shareable link. " +
|
|
143
|
+
"Returns the created share metadata including `link` (public URL), `slug`, `manageUrl`, " +
|
|
144
|
+
"and `deleteToken`. IMPORTANT: save the deleteToken/manageUrl — they are shown only once " +
|
|
145
|
+
"and are required to edit or delete the page later.", shareFields, (a) => apiRequest("POST", "/api/shares", { body: buildShareBody(a) }), { destructiveHint: false });
|
|
146
|
+
registerTool(server, "update_share", "Edit an existing share. Author-only — requires the manage_token (the deleteToken returned by " +
|
|
147
|
+
"create_share). Pass only the fields you want to change — unspecified fields keep their " +
|
|
148
|
+
"current values. Password intent: pass `password` to set a new one, `clear_password=true` to " +
|
|
149
|
+
"remove it, or leave both empty to keep it unchanged. Returns the updated metadata.", {
|
|
150
|
+
slug: z.string(),
|
|
151
|
+
manage_token: z.string().describe("The deleteToken from create_share (author's manage token)."),
|
|
152
|
+
...shareFields,
|
|
153
|
+
content: shareFields.content.optional(),
|
|
154
|
+
clear_password: z.boolean().optional().describe("Set true to remove the existing password."),
|
|
155
|
+
}, async (a) => {
|
|
156
|
+
// 서버의 PUT 은 full-replace 다 — 미지정 필드가 "유지"가 아니라 ShareUpdateIn 기본값
|
|
157
|
+
// (빈 제목·빈 태그·public·html)으로 리셋된다. unlisted 글이 public 으로 풀리거나
|
|
158
|
+
// 마크다운 글이 html 로 뒤바뀌는 사고를 막기 위해, 현재 원본을 manage API 로 읽어
|
|
159
|
+
// 미지정 필드를 채운 뒤 보낸다(같은 토큰으로 접근 가능하므로 추가 권한이 필요 없다).
|
|
160
|
+
const slug = encodeURIComponent(a.slug);
|
|
161
|
+
const cur = (await apiRequest("GET", `/api/shares/${slug}/manage`, {
|
|
162
|
+
query: { key: a.manage_token },
|
|
163
|
+
}));
|
|
164
|
+
const body = {
|
|
165
|
+
content: a.content ?? cur.content,
|
|
166
|
+
title: a.title ?? cur.title,
|
|
167
|
+
tags: a.tags ?? cur.tags,
|
|
168
|
+
content_type: a.content_type ?? cur.contentType,
|
|
169
|
+
visibility: a.visibility ?? cur.visibility,
|
|
170
|
+
};
|
|
171
|
+
if (a.password)
|
|
172
|
+
body.password = a.password;
|
|
173
|
+
if (a.clear_password !== undefined)
|
|
174
|
+
body.clearPassword = a.clear_password;
|
|
175
|
+
return apiRequest("PUT", `/api/shares/${slug}`, {
|
|
176
|
+
body,
|
|
177
|
+
headers: { "X-Delete-Token": a.manage_token },
|
|
178
|
+
});
|
|
179
|
+
}, { idempotentHint: true });
|
|
180
|
+
registerTool(server, "delete_share", "Delete a share. Provide manage_token to delete as the author, OR configure the " +
|
|
181
|
+
"DROPHTML_ADMIN_TOKEN environment variable to delete as an operator (takedown). " +
|
|
182
|
+
"`reason` is recorded in the deletion audit log (operator deletes). Returns {deleted: slug}.", {
|
|
183
|
+
slug: z.string(),
|
|
184
|
+
manage_token: z.string().optional().describe("Author's manage token. Omit to use operator ADMIN_TOKEN."),
|
|
185
|
+
reason: z.string().optional().describe("Optional takedown reason (audit log)."),
|
|
186
|
+
}, (a) => {
|
|
187
|
+
const headers = {};
|
|
188
|
+
if (a.manage_token)
|
|
189
|
+
headers["X-Delete-Token"] = a.manage_token;
|
|
190
|
+
else if (ADMIN_TOKEN)
|
|
191
|
+
headers["X-Admin-Token"] = ADMIN_TOKEN;
|
|
192
|
+
else
|
|
193
|
+
throw new Error("delete_share requires a `manage_token` argument or the DROPHTML_ADMIN_TOKEN env var.");
|
|
194
|
+
return apiRequest("DELETE", `/api/shares/${encodeURIComponent(a.slug)}`, {
|
|
195
|
+
headers,
|
|
196
|
+
query: { reason: a.reason },
|
|
197
|
+
});
|
|
198
|
+
}, { destructiveHint: true, idempotentHint: true });
|
|
199
|
+
// 읽기
|
|
200
|
+
registerTool(server, "search_shares", "Search or list public shares by title or tag substring. Returns {items, total}; item bodies " +
|
|
201
|
+
"are NOT included (use get_share for content).", {
|
|
202
|
+
query: z.string().optional().describe("Search text (title/tag). Empty lists all public shares."),
|
|
203
|
+
sort: z.enum(["popular", "recent"]).optional().describe("'popular' (default) or 'recent'."),
|
|
204
|
+
limit: z.number().int().optional().describe("Page size (server caps at 48)."),
|
|
205
|
+
offset: z.number().int().optional().describe("Pagination offset."),
|
|
206
|
+
}, (a) => apiRequest("GET", "/api/shares", {
|
|
207
|
+
query: { q: a.query, sort: a.sort, limit: a.limit, offset: a.offset },
|
|
208
|
+
}), { readOnlyHint: true });
|
|
209
|
+
registerTool(server, "get_share", "Fetch a share's content by slug. Without manage_token: returns the publicly served page from " +
|
|
210
|
+
"/raw (final HTML; for Markdown pages this is the render shell, not the original source; " +
|
|
211
|
+
"password-protected pages are NOT readable this way). With manage_token: returns the " +
|
|
212
|
+
"ORIGINAL source content + metadata, even for password-protected pages (author-only).", {
|
|
213
|
+
slug: z.string(),
|
|
214
|
+
manage_token: z.string().optional().describe("Author's manage token to get the original source."),
|
|
215
|
+
}, async (a) => {
|
|
216
|
+
const slug = encodeURIComponent(a.slug);
|
|
217
|
+
if (a.manage_token) {
|
|
218
|
+
return apiRequest("GET", `/api/shares/${slug}/manage`, { query: { key: a.manage_token } });
|
|
219
|
+
}
|
|
220
|
+
const resp = await doFetch("GET", `/raw/${slug}`);
|
|
221
|
+
const text = await resp.text();
|
|
222
|
+
if (!resp.ok) {
|
|
223
|
+
throw new Error(`DropHTML API GET /raw/${a.slug} → ${resp.status}: ${extractDetail(text, resp)}`);
|
|
224
|
+
}
|
|
225
|
+
// 비밀번호 게이트 폼은 200 OK 로 나온다(소셜 unfurl 크롤러가 비-200 에서 OG 를 읽지
|
|
226
|
+
// 않아서다). 폼 HTML 을 본문인 양 돌려주면 에이전트가 오인하므로, 정상 raw 응답
|
|
227
|
+
// (ETag 보유)과 헤더로 구분해 명확한 오류로 바꾼다(게이트 폼은 ETag 없이 no-store +
|
|
228
|
+
// X-Robots-Tag: noindex).
|
|
229
|
+
if (!resp.headers.get("etag") && (resp.headers.get("x-robots-tag") ?? "").includes("noindex")) {
|
|
230
|
+
throw new Error(`Share '${a.slug}' is password-protected — /raw serves an unlock form, not the content. ` +
|
|
231
|
+
"Pass manage_token to fetch the original source (author-only).");
|
|
232
|
+
}
|
|
233
|
+
return { slug: a.slug, url: `${BASE_URL}/raw/${a.slug}`, content: text };
|
|
234
|
+
}, { readOnlyHint: true });
|
|
235
|
+
registerTool(server, "get_daily_views", "Get a share's daily visit counts for the last `days` (1–365). Works for any existing slug " +
|
|
236
|
+
"(public or unlisted).", {
|
|
237
|
+
slug: z.string(),
|
|
238
|
+
days: z.number().int().optional().describe("Number of days (default 30, max 365)."),
|
|
239
|
+
}, (a) => apiRequest("GET", `/api/shares/${encodeURIComponent(a.slug)}/views/daily`, { query: { days: a.days } }), { readOnlyHint: true });
|
|
240
|
+
registerTool(server, "popular_tags", "Get popular tags across public shares.", {}, () => apiRequest("GET", "/api/tags"), { readOnlyHint: true });
|
|
241
|
+
registerTool(server, "site_stats", "Get site-wide aggregate stats (totals).", {}, () => apiRequest("GET", "/api/stats"), { readOnlyHint: true });
|
|
242
|
+
return server;
|
|
243
|
+
}
|
|
244
|
+
// --- transport: stdio (기본) / streamable-http ------------------------------
|
|
245
|
+
async function runStdio() {
|
|
246
|
+
const server = buildServer();
|
|
247
|
+
const transport = new StdioServerTransport();
|
|
248
|
+
await server.connect(transport);
|
|
249
|
+
}
|
|
250
|
+
async function runHttp(host, port) {
|
|
251
|
+
const httpServer = createHttpServer(async (req, res) => {
|
|
252
|
+
// 무상태 Streamable HTTP: POST /mcp 요청마다 서버+트랜스포트를 새로 만들고 닫는다.
|
|
253
|
+
if (req.method === "POST" && (req.url === "/mcp" || req.url?.startsWith("/mcp?"))) {
|
|
254
|
+
try {
|
|
255
|
+
const server = buildServer();
|
|
256
|
+
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
|
|
257
|
+
res.on("close", () => {
|
|
258
|
+
void transport.close();
|
|
259
|
+
void server.close();
|
|
260
|
+
});
|
|
261
|
+
await server.connect(transport);
|
|
262
|
+
// parsedBody 미전달 → SDK가 req 에서 직접 JSON 파싱(형식 오류도 JSON-RPC 오류로 응답).
|
|
263
|
+
await transport.handleRequest(req, res);
|
|
264
|
+
}
|
|
265
|
+
catch (e) {
|
|
266
|
+
if (!res.headersSent) {
|
|
267
|
+
res.writeHead(500, { "content-type": "application/json" });
|
|
268
|
+
res.end(JSON.stringify({ error: errMsg(e) }));
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
else {
|
|
273
|
+
res.writeHead(405, { "content-type": "text/plain", allow: "POST" }).end("Method Not Allowed");
|
|
274
|
+
}
|
|
275
|
+
});
|
|
276
|
+
// 포트 점유 등 listen 실패를 uncaughtException 크래시 대신 명확한 메시지로 종료한다.
|
|
277
|
+
httpServer.on("error", (e) => {
|
|
278
|
+
console.error(`DropHTML MCP http server error: ${e.message}`);
|
|
279
|
+
process.exit(1);
|
|
280
|
+
});
|
|
281
|
+
httpServer.listen(port, host, () => {
|
|
282
|
+
// 로그는 stderr로 (stdout은 stdio transport의 프로토콜 채널이라 오염 금지)
|
|
283
|
+
console.error(`DropHTML MCP (streamable-http) → http://${host}:${port}/mcp`);
|
|
284
|
+
});
|
|
285
|
+
}
|
|
286
|
+
export async function main() {
|
|
287
|
+
const transport = process.env.DROPHTML_MCP_TRANSPORT ?? "stdio";
|
|
288
|
+
if (transport === "stdio") {
|
|
289
|
+
await runStdio();
|
|
290
|
+
}
|
|
291
|
+
else if (transport === "streamable-http" || transport === "http") {
|
|
292
|
+
const host = process.env.DROPHTML_MCP_HOST ?? "127.0.0.1";
|
|
293
|
+
const port = Number(process.env.DROPHTML_MCP_PORT ?? "8765");
|
|
294
|
+
await runHttp(host, port);
|
|
295
|
+
}
|
|
296
|
+
else {
|
|
297
|
+
console.error(`Unknown DROPHTML_MCP_TRANSPORT: ${transport} (use 'stdio' or 'streamable-http')`);
|
|
298
|
+
process.exit(1);
|
|
299
|
+
}
|
|
300
|
+
}
|
package/dist/server.js
ADDED
package/package.json
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "drophtml-mcp",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "MCP server for DropHTML — publish and manage HTML/Markdown shares via the Model Context Protocol",
|
|
5
|
+
"license": "Apache-2.0",
|
|
6
|
+
"author": "drophtml.app",
|
|
7
|
+
"homepage": "https://drophtml.app",
|
|
8
|
+
"keywords": [
|
|
9
|
+
"mcp",
|
|
10
|
+
"model-context-protocol",
|
|
11
|
+
"drophtml",
|
|
12
|
+
"claude",
|
|
13
|
+
"html-hosting",
|
|
14
|
+
"markdown"
|
|
15
|
+
],
|
|
16
|
+
"type": "module",
|
|
17
|
+
"bin": {
|
|
18
|
+
"drophtml-mcp": "dist/server.js"
|
|
19
|
+
},
|
|
20
|
+
"files": [
|
|
21
|
+
"dist",
|
|
22
|
+
"LICENSE",
|
|
23
|
+
"NOTICE"
|
|
24
|
+
],
|
|
25
|
+
"engines": {
|
|
26
|
+
"node": ">=18"
|
|
27
|
+
},
|
|
28
|
+
"scripts": {
|
|
29
|
+
"build": "tsc",
|
|
30
|
+
"start": "node dist/server.js",
|
|
31
|
+
"test": "npm run build && node --test test/*.test.mjs",
|
|
32
|
+
"prepare": "tsc"
|
|
33
|
+
},
|
|
34
|
+
"dependencies": {
|
|
35
|
+
"@modelcontextprotocol/sdk": "^1.12.0",
|
|
36
|
+
"zod": "^3.23.8"
|
|
37
|
+
},
|
|
38
|
+
"devDependencies": {
|
|
39
|
+
"@types/node": "^22.0.0",
|
|
40
|
+
"typescript": "^5.5.0"
|
|
41
|
+
}
|
|
42
|
+
}
|