@topazlabs/mcp 0.1.12 → 0.1.14
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/README.md
CHANGED
|
@@ -1,15 +1,30 @@
|
|
|
1
1
|
# @topazlabs/mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@topazlabs/mcp)
|
|
4
|
+
[](https://www.npmjs.com/package/@topazlabs/mcp)
|
|
5
|
+
[](https://github.com/topazlabs/topaz-mcp/blob/main/LICENSE)
|
|
6
|
+
|
|
7
|
+
**AI image enhancement for LLMs.** An [MCP server](https://modelcontextprotocol.io) that lets Claude and other AI assistants enhance images using [Topaz Labs](https://www.topazlabs.com) AI models.
|
|
8
|
+
|
|
9
|
+
Topaz Labs makes AI-powered image and video enhancement software used by photographers, filmmakers, and developers worldwide.
|
|
10
|
+
|
|
11
|
+
## See It in Action
|
|
12
|
+
|
|
13
|
+
| Before | After |
|
|
14
|
+
|--------|-------|
|
|
15
|
+
|  |  |
|
|
16
|
+
|
|
17
|
+
Enhanced with the **Wonder 2** model. [View interactive comparison →](https://compare.topazlabs.com/share/image?src1=https%3A%2F%2Fcdn.prod.website-files.com%2F6005fac27a49a9cd477afb63%2F696fce95820c4035f17a1159_wondercompare-fidelity-1-original.webp&src1label=Before&src2=https%3A%2F%2Fcdn.prod.website-files.com%2F6005fac27a49a9cd477afb63%2F696fce96e2494c7a7935814b_wondercompare-fidelity-1-wonder2.webp&src2label=After&view=slider&zoom=1)
|
|
4
18
|
|
|
5
19
|
## Quick Start
|
|
6
20
|
|
|
7
|
-
###
|
|
21
|
+
### 1. Get an API key
|
|
22
|
+
|
|
23
|
+
Sign up at [developer.topazlabs.com](https://developer.topazlabs.com/getting-started/how-do-i-get-my-api-key).
|
|
8
24
|
|
|
9
|
-
Add to your
|
|
25
|
+
### 2. Add to your MCP client
|
|
10
26
|
|
|
11
|
-
|
|
12
|
-
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
27
|
+
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
|
|
13
28
|
|
|
14
29
|
```json
|
|
15
30
|
{
|
|
@@ -25,15 +40,26 @@ Add to your Claude Desktop config:
|
|
|
25
40
|
}
|
|
26
41
|
```
|
|
27
42
|
|
|
28
|
-
|
|
43
|
+
### 3. Enhance images
|
|
44
|
+
|
|
45
|
+
> **You:** "Enhance ~/Desktop/photo.jpg with Wonder 2"
|
|
46
|
+
>
|
|
47
|
+
> **Claude:** I'll enhance your photo using Topaz Labs' Wonder 2 model.
|
|
48
|
+
>
|
|
49
|
+
> *\[calls image-enhance tool\]*
|
|
50
|
+
>
|
|
51
|
+
> Here's your enhanced image -- upscaled and sharpened with improved detail and clarity.
|
|
52
|
+
|
|
53
|
+
> **Note:** This tool requires a file path or URL — it cannot process images uploaded directly in the chat. It works best with **Claude Cowork**, which has file system access. It does not work in Claude Chat mode (no file system access).
|
|
29
54
|
|
|
30
55
|
## Compatibility
|
|
31
56
|
|
|
32
|
-
This server uses **stdio transport**,
|
|
57
|
+
This server uses **stdio transport**, supported by all major MCP desktop clients:
|
|
33
58
|
|
|
34
59
|
| Client | Status |
|
|
35
60
|
|--------|--------|
|
|
36
|
-
| Claude
|
|
61
|
+
| Claude Cowork | ✅ (recommended — has file system access) |
|
|
62
|
+
| Claude Desktop (Chat) | ⚠️ Requires user to provide file paths manually |
|
|
37
63
|
| Cursor | ✅ |
|
|
38
64
|
| Windsurf | ✅ |
|
|
39
65
|
| VS Code (Copilot) | ✅ |
|
|
@@ -74,19 +100,18 @@ model: "Standard V2" # Optional: defaults to Standard V2
|
|
|
74
100
|
|
|
75
101
|
| Variable | Required | Description |
|
|
76
102
|
|----------|----------|-------------|
|
|
77
|
-
| `TOPAZ_API_KEY` | Yes | Topaz Labs API key |
|
|
103
|
+
| `TOPAZ_API_KEY` | Yes | [Topaz Labs API key](https://developer.topazlabs.com/getting-started/how-do-i-get-my-api-key) |
|
|
78
104
|
|
|
79
105
|
## Architecture
|
|
80
106
|
|
|
81
107
|
```
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
test/ — Vitest test suite
|
|
108
|
+
src/
|
|
109
|
+
api/ -- Topaz API client, types, model definitions
|
|
110
|
+
lib/ -- Path security, URL fetching utilities
|
|
111
|
+
tools/ -- enhance tool handler
|
|
112
|
+
server.ts -- MCP server setup and tool registration
|
|
113
|
+
main.ts -- Entry point (stdio transport)
|
|
114
|
+
test/ -- Vitest test suite
|
|
90
115
|
```
|
|
91
116
|
|
|
92
117
|
## Development
|
|
@@ -97,26 +122,16 @@ npm run build
|
|
|
97
122
|
npm test
|
|
98
123
|
```
|
|
99
124
|
|
|
100
|
-
|
|
125
|
+
## Limitations
|
|
101
126
|
|
|
102
|
-
|
|
127
|
+
- **Image only** -- video enhancement is not yet supported
|
|
128
|
+
- **Paid API key required** -- sign up at [developer.topazlabs.com](https://developer.topazlabs.com/getting-started/how-do-i-get-my-api-key)
|
|
129
|
+
- **Cloud processing** -- images are sent to the Topaz Labs API for enhancement
|
|
103
130
|
|
|
104
|
-
|
|
105
|
-
# 1. Build and test
|
|
106
|
-
npm run build && npm test
|
|
107
|
-
|
|
108
|
-
# 2. Publish
|
|
109
|
-
npm publish -w packages/mcp
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
To bump the version before publishing:
|
|
113
|
-
|
|
114
|
-
```bash
|
|
115
|
-
npm version patch -w packages/mcp
|
|
116
|
-
```
|
|
131
|
+
## Contributing
|
|
117
132
|
|
|
118
|
-
|
|
133
|
+
Found a bug or have a feature request? [Open an issue](https://github.com/topazlabs/topaz-mcp/issues) on GitHub.
|
|
119
134
|
|
|
120
135
|
## License
|
|
121
136
|
|
|
122
|
-
MIT
|
|
137
|
+
MIT -- [Topaz Labs](https://www.topazlabs.com)
|
|
@@ -4,14 +4,8 @@
|
|
|
4
4
|
* /sessions/<id>/mnt/<folder>/ which maps to ~/<folder>/ on the host.
|
|
5
5
|
*/
|
|
6
6
|
export declare function translateSandboxPath(inputPath: string): string;
|
|
7
|
-
/**
|
|
8
|
-
* Validate a file path for reading. Returns the resolved absolute path.
|
|
9
|
-
* Expands ~, translates sandbox paths, blocks sensitive directories.
|
|
10
|
-
*/
|
|
7
|
+
/** Validate a file path for reading. */
|
|
11
8
|
export declare function validateReadPath(inputPath: string): string;
|
|
12
|
-
/**
|
|
13
|
-
* Validate a file path for writing. Returns the resolved absolute path.
|
|
14
|
-
* Expands ~, translates sandbox paths, restricts to CWD + temp + TOPAZ_ALLOWED_DIRS.
|
|
15
|
-
*/
|
|
9
|
+
/** Validate a file path for writing. */
|
|
16
10
|
export declare function validateWritePath(inputPath: string): string;
|
|
17
11
|
//# sourceMappingURL=path-security.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"path-security.d.ts","sourceRoot":"","sources":["../../src/lib/path-security.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"path-security.d.ts","sourceRoot":"","sources":["../../src/lib/path-security.ts"],"names":[],"mappings":"AAsEA;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAM9D;AAuBD,wCAAwC;AACxC,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wCAAwC;AACxC,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D"}
|
|
@@ -1,10 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Path security — validates file paths.
|
|
3
3
|
*
|
|
4
|
-
* -
|
|
5
|
-
* - Writes: CWD + temp + TOPAZ_ALLOWED_DIRS
|
|
6
|
-
* - Always blocks sensitive paths (/etc, ~/.ssh, etc.)
|
|
7
|
-
* - Blocks symlinks that escape allowed directories (writes only)
|
|
4
|
+
* - Blocks sensitive paths (/etc, ~/.ssh, ~/.aws, etc.)
|
|
8
5
|
* - Expands ~ to home directory
|
|
9
6
|
* - Translates Claude Cowork sandbox paths to real macOS paths
|
|
10
7
|
*/
|
|
@@ -41,14 +38,6 @@ function isSensitivePath(p) {
|
|
|
41
38
|
}
|
|
42
39
|
return false;
|
|
43
40
|
}
|
|
44
|
-
function resolveReal(p) {
|
|
45
|
-
try {
|
|
46
|
-
return fs.realpathSync(p);
|
|
47
|
-
}
|
|
48
|
-
catch {
|
|
49
|
-
return p;
|
|
50
|
-
}
|
|
51
|
-
}
|
|
52
41
|
/**
|
|
53
42
|
* Resolve a path safely, handling the case where the file doesn't exist yet.
|
|
54
43
|
* For non-existent files, resolves the parent directory (which must exist)
|
|
@@ -69,63 +58,6 @@ function resolveRealSafe(p) {
|
|
|
69
58
|
}
|
|
70
59
|
}
|
|
71
60
|
}
|
|
72
|
-
/**
|
|
73
|
-
* Walk every component of a path checking for symlinks that escape allowed dirs.
|
|
74
|
-
* Returns true if any symlink component resolves outside allowed directories.
|
|
75
|
-
*/
|
|
76
|
-
function hasSymlinkEscape(filePath) {
|
|
77
|
-
const allowed = getWriteAllowedDirs();
|
|
78
|
-
const parts = filePath.split(path.sep);
|
|
79
|
-
let current = parts[0] === "" ? path.sep : parts[0];
|
|
80
|
-
for (let i = 1; i < parts.length; i++) {
|
|
81
|
-
current = path.join(current, parts[i]);
|
|
82
|
-
try {
|
|
83
|
-
const stat = fs.lstatSync(current);
|
|
84
|
-
if (stat.isSymbolicLink()) {
|
|
85
|
-
const target = fs.realpathSync(current);
|
|
86
|
-
const isWithinAllowed = allowed.some((dir) => target === dir || target.startsWith(dir + path.sep));
|
|
87
|
-
const isAncestorOfAllowed = allowed.some((dir) => dir.startsWith(target + path.sep));
|
|
88
|
-
if (!isWithinAllowed && !isAncestorOfAllowed) {
|
|
89
|
-
return true;
|
|
90
|
-
}
|
|
91
|
-
}
|
|
92
|
-
}
|
|
93
|
-
catch {
|
|
94
|
-
break;
|
|
95
|
-
}
|
|
96
|
-
}
|
|
97
|
-
return false;
|
|
98
|
-
}
|
|
99
|
-
/** Directories where writes are allowed: CWD + temp + TOPAZ_ALLOWED_DIRS */
|
|
100
|
-
function getWriteAllowedDirs() {
|
|
101
|
-
const cwd = path.resolve(process.cwd());
|
|
102
|
-
const cwdReal = resolveReal(cwd);
|
|
103
|
-
const tmpDir = path.resolve(os.tmpdir());
|
|
104
|
-
const tmpDirReal = resolveReal(tmpDir);
|
|
105
|
-
const dirs = [cwd, tmpDir];
|
|
106
|
-
if (cwdReal !== cwd)
|
|
107
|
-
dirs.push(cwdReal);
|
|
108
|
-
if (tmpDirReal !== tmpDir)
|
|
109
|
-
dirs.push(tmpDirReal);
|
|
110
|
-
const envDirs = process.env.TOPAZ_ALLOWED_DIRS;
|
|
111
|
-
if (envDirs) {
|
|
112
|
-
for (const d of envDirs.split(",")) {
|
|
113
|
-
const trimmed = d.trim();
|
|
114
|
-
if (trimmed) {
|
|
115
|
-
const resolved = path.resolve(trimmed);
|
|
116
|
-
dirs.push(resolved);
|
|
117
|
-
const real = resolveReal(resolved);
|
|
118
|
-
if (real !== resolved)
|
|
119
|
-
dirs.push(real);
|
|
120
|
-
}
|
|
121
|
-
}
|
|
122
|
-
}
|
|
123
|
-
return dirs;
|
|
124
|
-
}
|
|
125
|
-
function isWithinWriteAllowedDirs(realPath) {
|
|
126
|
-
const allowed = getWriteAllowedDirs();
|
|
127
|
-
return allowed.some((dir) => realPath === dir || realPath.startsWith(dir + path.sep));
|
|
128
|
-
}
|
|
129
61
|
/** Expand ~ to the user's home directory */
|
|
130
62
|
function expandTilde(p) {
|
|
131
63
|
if (p === "~")
|
|
@@ -151,10 +83,10 @@ function normalizePath(inputPath) {
|
|
|
151
83
|
return translateSandboxPath(expandTilde(inputPath));
|
|
152
84
|
}
|
|
153
85
|
/**
|
|
154
|
-
* Validate a
|
|
86
|
+
* Validate a path and return the resolved absolute path.
|
|
155
87
|
* Expands ~, translates sandbox paths, blocks sensitive directories.
|
|
156
88
|
*/
|
|
157
|
-
|
|
89
|
+
function validatePath(inputPath) {
|
|
158
90
|
const normalized = normalizePath(inputPath);
|
|
159
91
|
const resolved = path.resolve(normalized);
|
|
160
92
|
const realPath = resolveRealSafe(resolved);
|
|
@@ -163,23 +95,12 @@ export function validateReadPath(inputPath) {
|
|
|
163
95
|
}
|
|
164
96
|
return resolved;
|
|
165
97
|
}
|
|
166
|
-
/**
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
98
|
+
/** Validate a file path for reading. */
|
|
99
|
+
export function validateReadPath(inputPath) {
|
|
100
|
+
return validatePath(inputPath);
|
|
101
|
+
}
|
|
102
|
+
/** Validate a file path for writing. */
|
|
170
103
|
export function validateWritePath(inputPath) {
|
|
171
|
-
|
|
172
|
-
const resolved = path.resolve(normalized);
|
|
173
|
-
const realPath = resolveRealSafe(resolved);
|
|
174
|
-
if (isSensitivePath(resolved) || isSensitivePath(realPath)) {
|
|
175
|
-
throw new Error("Access denied: path is in a restricted location");
|
|
176
|
-
}
|
|
177
|
-
if (!isWithinWriteAllowedDirs(realPath)) {
|
|
178
|
-
throw new Error("Access denied: path is outside allowed directories");
|
|
179
|
-
}
|
|
180
|
-
if (hasSymlinkEscape(resolved)) {
|
|
181
|
-
throw new Error("Access denied: path contains a symlink that escapes allowed directories");
|
|
182
|
-
}
|
|
183
|
-
return resolved;
|
|
104
|
+
return validatePath(inputPath);
|
|
184
105
|
}
|
|
185
106
|
//# sourceMappingURL=path-security.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"path-security.js","sourceRoot":"","sources":["../../src/lib/path-security.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"path-security.js","sourceRoot":"","sources":["../../src/lib/path-security.ts"],"names":[],"mappings":"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"}
|