@evrenta/mcp 0.0.0-stage → 0.1.1
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 +21 -0
- package/README.md +119 -2
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +32 -0
- package/dist/client.d.ts +27 -0
- package/dist/client.js +208 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +6 -0
- package/dist/result.d.ts +3 -0
- package/dist/result.js +16 -0
- package/dist/server.d.ts +5 -0
- package/dist/server.js +17 -0
- package/dist/tools.d.ts +10 -0
- package/dist/tools.js +337 -0
- package/dist/utils.d.ts +6 -0
- package/dist/utils.js +72 -0
- package/package.json +77 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Stefan Kumarasinghe
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,120 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="assets/mascot.knowledge.png" alt="Evrenta’s Knowledge mascot, a waving purple page with connected nodes" width="240" />
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">Evrenta MCP</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center"><strong>Connect your AI client to the workspace spaces and linked task boards your agent token allows.</strong></p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-24%2B-339933?logo=nodedotjs&logoColor=white" alt="Node.js 24 or later" /></a>
|
|
11
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-4051B5.svg" alt="MIT License" /></a>
|
|
12
|
+
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/Protocol-MCP-7158E2.svg" alt="Model Context Protocol" /></a>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
Evrenta MCP runs on your machine and connects to a compatible workspace service. The same package can connect to different instances; each client entry supplies that instance’s URL and agent token. The service checks token permissions on every request.
|
|
16
|
+
|
|
17
|
+
[Quick start](#quick-start) · [Permissions](#permissions) · [Team use](#team-use) · [Troubleshooting](#troubleshooting) · [License](#license)
|
|
18
|
+
|
|
19
|
+
## Quick start
|
|
20
|
+
|
|
21
|
+
You’ll need the URL of a compatible instance, an MCP-compatible AI client, and Node.js 24 or later.
|
|
22
|
+
|
|
23
|
+
### 1. Create an agent token
|
|
24
|
+
|
|
25
|
+
In the target instance, open **Profile → API tokens → New token**. Choose **Agent — AI and automation**, select the spaces to connect, set an expiry, and copy the token. The instance shows it only once.
|
|
26
|
+
|
|
27
|
+
Start with read access. You can add permissions later if your team wants the AI client to make changes.
|
|
28
|
+
|
|
29
|
+
### 2. Install the package (optional)
|
|
30
|
+
|
|
31
|
+
When the npm package is available, you can install it globally:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
npm install -g @evrenta/mcp
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The AI client configuration below uses `npx`, so a separate global install is optional.
|
|
38
|
+
|
|
39
|
+
### 3. Add the server to your AI client
|
|
40
|
+
|
|
41
|
+
Add this entry in the client’s MCP settings. Replace the example URL and token with your own. `workspace` is only a local name in the client; you can change it. Keep the token in private client settings or a secret store, and don’t commit it to a shared project.
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{
|
|
45
|
+
"mcpServers": {
|
|
46
|
+
"workspace": {
|
|
47
|
+
"command": "npx",
|
|
48
|
+
"args": ["-y", "@evrenta/mcp"],
|
|
49
|
+
"env": {
|
|
50
|
+
"APP_API_URL": "https://your-instance.example.com",
|
|
51
|
+
"APP_API_TOKEN": "<your-agent-token>"
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Use the target instance’s service origin, without a space path. `/api` is optional. Hosted services must use HTTPS; plain HTTP is allowed for local development. Add another `mcpServers` entry with its own URL and token to connect to another instance.
|
|
59
|
+
|
|
60
|
+
If npm can’t find `@evrenta/mcp` yet, run it from a source checkout:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
git clone https://github.com/Evrenta/mcp.git
|
|
64
|
+
cd mcp
|
|
65
|
+
npm ci
|
|
66
|
+
npm run build
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
In your MCP settings, use `node` as the command and the full path to `mcp/dist/index.js` as its argument. Keep only the `APP_API_URL` and `APP_API_TOKEN` values shown above.
|
|
70
|
+
|
|
71
|
+
### 4. Connect and try a search
|
|
72
|
+
|
|
73
|
+
Restart or reload the AI client, then ask it to call `list_spaces`. Try a read-only request, for example:
|
|
74
|
+
|
|
75
|
+
> Search our onboarding pages for the equipment return process and show me the most relevant page.
|
|
76
|
+
|
|
77
|
+
If the token can access one space, it is selected automatically. If it can access more than one, choose a `spaceId` from `list_spaces` for each space-specific request.
|
|
78
|
+
|
|
79
|
+
## Permissions
|
|
80
|
+
|
|
81
|
+
Grant only what each person needs. Permissions can differ by space.
|
|
82
|
+
|
|
83
|
+
| Team task | Permissions |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| Find and read pages | `content.read`, `search.query` |
|
|
86
|
+
| Create or edit pages | Add `content.write` |
|
|
87
|
+
| Delete pages or files | Add `content.delete` |
|
|
88
|
+
| Read revision history | Add `revisions.read` |
|
|
89
|
+
| Create or remove snapshots; sync a connected repository | Add `revisions.manage` |
|
|
90
|
+
| Share a page | Add `content.read` and `content.share` |
|
|
91
|
+
| Work with drawing shares | Add the required `drawings.read`, `drawings.write`, or `drawings.share` permissions |
|
|
92
|
+
| View tasks on a linked task board | Add `board.read` |
|
|
93
|
+
| Create or update linked tasks | Add `board.manage` |
|
|
94
|
+
|
|
95
|
+
## Team use
|
|
96
|
+
|
|
97
|
+
Give each teammate their own token rather than sharing one. This keeps access scoped to their account and spaces. Start with search and read access; add write or sharing permissions only when your team is ready.
|
|
98
|
+
|
|
99
|
+
Common ways to use the connection:
|
|
100
|
+
|
|
101
|
+
- **Find information:** Search workspace pages and ask for the page name along with the answer so a teammate can check the source.
|
|
102
|
+
- **Improve documentation:** Ask for a suggested edit first, then allow page updates when appropriate.
|
|
103
|
+
- **Track follow-ups:** List, create, and update tasks on the task board linked to the selected space. These tools cover linked tasks, not the full project-management API.
|
|
104
|
+
- **Review changes:** Inspect page history or create a snapshot before a larger edit.
|
|
105
|
+
|
|
106
|
+
The AI client shows each tool’s inputs and required permissions. Review proposed edits before applying them. Deletes are permanent; sharing a page or drawing can give others access through its link.
|
|
107
|
+
|
|
108
|
+
## Troubleshooting
|
|
109
|
+
|
|
110
|
+
| What you see | What to check |
|
|
111
|
+
| --- | --- |
|
|
112
|
+
| The MCP server doesn’t appear | Confirm Node.js 24+ is installed, then restart the client. |
|
|
113
|
+
| No spaces are listed | Check that the token is active and includes at least one space. |
|
|
114
|
+
| A tool says access is denied | Add the required permission to the token for that space. |
|
|
115
|
+
| A request needs a `spaceId` | Call `list_spaces`, choose the intended space, and pass its ID. |
|
|
116
|
+
| The service URL is rejected | Use the instance origin, not a space URL; hosted services need HTTPS. |
|
|
117
|
+
|
|
118
|
+
## License
|
|
119
|
+
|
|
120
|
+
MIT © Stefan Kumarasinghe. See [LICENSE](LICENSE).
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function runCli(): Promise<void>;
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { stdin } from "node:process";
|
|
2
|
+
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
|
|
3
|
+
import { createMcpServer } from "./server.js";
|
|
4
|
+
export async function runCli() {
|
|
5
|
+
const [command] = process.argv.slice(2);
|
|
6
|
+
if (command && ["-h", "--help", "help"].includes(command)) {
|
|
7
|
+
console.log(`evrenta-mcp — Model Context Protocol server (stdio)
|
|
8
|
+
|
|
9
|
+
Usage:
|
|
10
|
+
evrenta-mcp Start the MCP server
|
|
11
|
+
evrenta-mcp serve Start the MCP server
|
|
12
|
+
evrenta-mcp --help Show this help
|
|
13
|
+
|
|
14
|
+
Required environment:
|
|
15
|
+
APP_API_TOKEN Scoped service agent token
|
|
16
|
+
Optional environment:
|
|
17
|
+
APP_API_URL Service origin URL (default: http://localhost:3000)
|
|
18
|
+
`);
|
|
19
|
+
return;
|
|
20
|
+
}
|
|
21
|
+
if (command && !["serve", "stdio", "run"].includes(command)) {
|
|
22
|
+
console.error(`Unknown command: ${command}. Run evrenta-mcp --help.`);
|
|
23
|
+
process.exitCode = 1;
|
|
24
|
+
return;
|
|
25
|
+
}
|
|
26
|
+
if (stdin.isTTY && !command) {
|
|
27
|
+
console.log("evrenta-mcp is a stdio server. Configure it in your MCP client or run `evrenta-mcp serve`.");
|
|
28
|
+
return;
|
|
29
|
+
}
|
|
30
|
+
const server = createMcpServer();
|
|
31
|
+
await server.connect(new StdioServerTransport());
|
|
32
|
+
}
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
export type ApplicationSpace = {
|
|
2
|
+
id: string;
|
|
3
|
+
name: string;
|
|
4
|
+
permissions: string[];
|
|
5
|
+
};
|
|
6
|
+
export type ApplicationResponse = {
|
|
7
|
+
readonly bytes: Uint8Array;
|
|
8
|
+
readonly headers: Headers;
|
|
9
|
+
readonly contentType: string;
|
|
10
|
+
};
|
|
11
|
+
/** Small bearer-authenticated client for the compatible workspace space API. */
|
|
12
|
+
export declare class ApplicationClient {
|
|
13
|
+
#private;
|
|
14
|
+
readonly baseUrl: string;
|
|
15
|
+
constructor(baseUrl: string, token: string);
|
|
16
|
+
spaces(): Promise<ApplicationSpace[]>;
|
|
17
|
+
resolveSpace(spaceId?: string): Promise<string>;
|
|
18
|
+
inSpace<T>(spaceId: string, operation: () => Promise<T>): Promise<T>;
|
|
19
|
+
json<T = unknown>(path: string, init?: RequestInit): Promise<T>;
|
|
20
|
+
bytes(path: string, maxBytes: number): Promise<ApplicationResponse>;
|
|
21
|
+
text(path: string, init?: RequestInit): Promise<{
|
|
22
|
+
text: string;
|
|
23
|
+
headers: Headers;
|
|
24
|
+
}>;
|
|
25
|
+
head(path: string, headers?: HeadersInit): Promise<Headers>;
|
|
26
|
+
private request;
|
|
27
|
+
}
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
import { AsyncLocalStorage } from "node:async_hooks";
|
|
2
|
+
import { normalizeBaseUrl } from "./utils.js";
|
|
3
|
+
const MAX_ERROR_BYTES = 64 * 1024;
|
|
4
|
+
const MAX_JSON_BYTES = 8 * 1024 * 1024;
|
|
5
|
+
const SPACE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
6
|
+
const API_ORIGIN = "https://app.invalid";
|
|
7
|
+
function validateApiPath(path) {
|
|
8
|
+
const queryStart = path.indexOf("?");
|
|
9
|
+
const pathname = queryStart < 0 ? path : path.slice(0, queryStart);
|
|
10
|
+
let resolved;
|
|
11
|
+
let decodedPath;
|
|
12
|
+
try {
|
|
13
|
+
resolved = new URL(path, API_ORIGIN);
|
|
14
|
+
decodedPath = decodeURIComponent(pathname);
|
|
15
|
+
}
|
|
16
|
+
catch {
|
|
17
|
+
throw new Error("API paths must be valid absolute API paths");
|
|
18
|
+
}
|
|
19
|
+
if (!path.startsWith("/api/") ||
|
|
20
|
+
path.startsWith("//") ||
|
|
21
|
+
path.includes("#") ||
|
|
22
|
+
resolved.origin !== API_ORIGIN ||
|
|
23
|
+
resolved.pathname !== pathname ||
|
|
24
|
+
!resolved.pathname.startsWith("/api/") ||
|
|
25
|
+
decodedPath.split("/").some((segment) => segment === "." ||
|
|
26
|
+
segment === ".." ||
|
|
27
|
+
segment.includes("\\") ||
|
|
28
|
+
[...segment].some((character) => {
|
|
29
|
+
const code = character.charCodeAt(0);
|
|
30
|
+
return code < 0x20 || code === 0x7f;
|
|
31
|
+
}))) {
|
|
32
|
+
throw new Error("API paths must stay within /api/");
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
/** Small bearer-authenticated client for the compatible workspace space API. */
|
|
36
|
+
export class ApplicationClient {
|
|
37
|
+
baseUrl;
|
|
38
|
+
#token;
|
|
39
|
+
#space = new AsyncLocalStorage();
|
|
40
|
+
constructor(baseUrl, token) {
|
|
41
|
+
this.baseUrl = normalizeBaseUrl(baseUrl);
|
|
42
|
+
if (!token.trim())
|
|
43
|
+
throw new Error("An API token is required");
|
|
44
|
+
this.#token = token.trim();
|
|
45
|
+
}
|
|
46
|
+
async spaces() {
|
|
47
|
+
const result = await this.json("/api/mcp/spaces");
|
|
48
|
+
if (!result ||
|
|
49
|
+
!Array.isArray(result.spaces) ||
|
|
50
|
+
!result.spaces.every((space) => space &&
|
|
51
|
+
typeof space === "object" &&
|
|
52
|
+
SPACE_ID.test(space.id) &&
|
|
53
|
+
typeof space.name === "string" &&
|
|
54
|
+
Array.isArray(space.permissions) &&
|
|
55
|
+
space.permissions.every((permission) => typeof permission === "string"))) {
|
|
56
|
+
throw new Error("The API returned an invalid space discovery response");
|
|
57
|
+
}
|
|
58
|
+
return result.spaces;
|
|
59
|
+
}
|
|
60
|
+
async resolveSpace(spaceId) {
|
|
61
|
+
if (spaceId !== undefined) {
|
|
62
|
+
if (!SPACE_ID.test(spaceId))
|
|
63
|
+
throw new Error("spaceId must be a valid space ID");
|
|
64
|
+
return spaceId;
|
|
65
|
+
}
|
|
66
|
+
const spaces = await this.spaces();
|
|
67
|
+
if (spaces.length === 1)
|
|
68
|
+
return spaces[0].id;
|
|
69
|
+
if (spaces.length === 0) {
|
|
70
|
+
throw new Error("This API token has no accessible spaces");
|
|
71
|
+
}
|
|
72
|
+
throw new Error("Choose an accessible space with the spaceId argument, or call list_spaces first");
|
|
73
|
+
}
|
|
74
|
+
inSpace(spaceId, operation) {
|
|
75
|
+
if (!SPACE_ID.test(spaceId))
|
|
76
|
+
throw new Error("spaceId must be a valid space ID");
|
|
77
|
+
return this.#space.run(spaceId, operation);
|
|
78
|
+
}
|
|
79
|
+
async json(path, init) {
|
|
80
|
+
const response = await this.request(path, init);
|
|
81
|
+
const bytes = await readBounded(response, MAX_JSON_BYTES);
|
|
82
|
+
if (!response.ok)
|
|
83
|
+
throw apiError(path, response, bytes);
|
|
84
|
+
if (bytes.length === 0)
|
|
85
|
+
return null;
|
|
86
|
+
try {
|
|
87
|
+
const value = JSON.parse(new TextDecoder().decode(bytes));
|
|
88
|
+
if (value &&
|
|
89
|
+
typeof value === "object" &&
|
|
90
|
+
!Array.isArray(value) &&
|
|
91
|
+
Object.hasOwn(value, "data")) {
|
|
92
|
+
return value.data;
|
|
93
|
+
}
|
|
94
|
+
return value;
|
|
95
|
+
}
|
|
96
|
+
catch {
|
|
97
|
+
throw new Error(`${path}: The API returned invalid JSON`);
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
async bytes(path, maxBytes) {
|
|
101
|
+
const response = await this.request(path);
|
|
102
|
+
const bytes = await readBounded(response, response.ok ? maxBytes : MAX_ERROR_BYTES);
|
|
103
|
+
if (!response.ok)
|
|
104
|
+
throw apiError(path, response, bytes);
|
|
105
|
+
return {
|
|
106
|
+
bytes,
|
|
107
|
+
headers: response.headers,
|
|
108
|
+
contentType: response.headers.get("x-content-type") ??
|
|
109
|
+
response.headers.get("content-type") ??
|
|
110
|
+
"application/octet-stream",
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
async text(path, init) {
|
|
114
|
+
const response = await this.request(path, init);
|
|
115
|
+
const bytes = await readBounded(response, response.ok ? MAX_JSON_BYTES : MAX_ERROR_BYTES);
|
|
116
|
+
if (!response.ok)
|
|
117
|
+
throw apiError(path, response, bytes);
|
|
118
|
+
return { text: new TextDecoder().decode(bytes), headers: response.headers };
|
|
119
|
+
}
|
|
120
|
+
async head(path, headers) {
|
|
121
|
+
const response = await this.request(path, { method: "HEAD", headers });
|
|
122
|
+
if (!response.ok) {
|
|
123
|
+
throw apiError(path, response, await readBounded(response, MAX_ERROR_BYTES));
|
|
124
|
+
}
|
|
125
|
+
return response.headers;
|
|
126
|
+
}
|
|
127
|
+
async request(path, init = {}) {
|
|
128
|
+
validateApiPath(path);
|
|
129
|
+
const headers = new Headers(init.headers);
|
|
130
|
+
headers.set("Authorization", `Bearer ${this.#token}`);
|
|
131
|
+
headers.set("Accept", "application/json, text/plain, */*");
|
|
132
|
+
if (init.body != null && !headers.has("Content-Type")) {
|
|
133
|
+
headers.set("Content-Type", "application/json");
|
|
134
|
+
}
|
|
135
|
+
const timeout = AbortSignal.timeout(15_000);
|
|
136
|
+
const signal = init.signal
|
|
137
|
+
? AbortSignal.any([init.signal, timeout])
|
|
138
|
+
: timeout;
|
|
139
|
+
const spaceId = this.#space.getStore();
|
|
140
|
+
const endpoint = spaceId && path !== "/api/mcp/spaces"
|
|
141
|
+
? `${this.baseUrl}/api/mcp/spaces/${encodeURIComponent(spaceId)}${path}`
|
|
142
|
+
: `${this.baseUrl}${path}`;
|
|
143
|
+
return fetch(endpoint, {
|
|
144
|
+
...init,
|
|
145
|
+
headers,
|
|
146
|
+
signal,
|
|
147
|
+
redirect: "error",
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
async function readBounded(response, maxBytes) {
|
|
152
|
+
if (!response.body)
|
|
153
|
+
return new Uint8Array();
|
|
154
|
+
const reader = response.body.getReader();
|
|
155
|
+
const chunks = [];
|
|
156
|
+
let size = 0;
|
|
157
|
+
try {
|
|
158
|
+
while (true) {
|
|
159
|
+
const { done, value } = await reader.read();
|
|
160
|
+
if (done)
|
|
161
|
+
break;
|
|
162
|
+
size += value.byteLength;
|
|
163
|
+
if (size > maxBytes) {
|
|
164
|
+
await reader.cancel();
|
|
165
|
+
throw new Error(`API response exceeds the ${maxBytes}-byte limit`);
|
|
166
|
+
}
|
|
167
|
+
chunks.push(value);
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
finally {
|
|
171
|
+
reader.releaseLock();
|
|
172
|
+
}
|
|
173
|
+
const result = new Uint8Array(size);
|
|
174
|
+
let offset = 0;
|
|
175
|
+
for (const chunk of chunks) {
|
|
176
|
+
result.set(chunk, offset);
|
|
177
|
+
offset += chunk.byteLength;
|
|
178
|
+
}
|
|
179
|
+
return result;
|
|
180
|
+
}
|
|
181
|
+
function apiError(path, response, bytes) {
|
|
182
|
+
const body = new TextDecoder().decode(bytes).trim();
|
|
183
|
+
let message = `HTTP ${response.status}`;
|
|
184
|
+
if (body) {
|
|
185
|
+
try {
|
|
186
|
+
const parsed = JSON.parse(body);
|
|
187
|
+
if (parsed && typeof parsed === "object") {
|
|
188
|
+
const record = parsed;
|
|
189
|
+
const nested = record.error;
|
|
190
|
+
const nestedMessage = nested && typeof nested === "object"
|
|
191
|
+
? nested.message
|
|
192
|
+
: undefined;
|
|
193
|
+
const detail = record.message ?? nestedMessage;
|
|
194
|
+
if (typeof detail === "string")
|
|
195
|
+
message = detail;
|
|
196
|
+
else
|
|
197
|
+
message = JSON.stringify(parsed);
|
|
198
|
+
}
|
|
199
|
+
else {
|
|
200
|
+
message = typeof parsed === "string" ? parsed : JSON.stringify(parsed);
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
catch {
|
|
204
|
+
message = body.slice(0, 500);
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
return new Error(`${path}: ${message}`);
|
|
208
|
+
}
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
package/dist/result.d.ts
ADDED
package/dist/result.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
export function textResult(data, isError = false) {
|
|
2
|
+
return {
|
|
3
|
+
content: [
|
|
4
|
+
{
|
|
5
|
+
type: "text",
|
|
6
|
+
text: typeof data === "string"
|
|
7
|
+
? data
|
|
8
|
+
: (JSON.stringify(data, null, 2) ?? ""),
|
|
9
|
+
},
|
|
10
|
+
],
|
|
11
|
+
isError,
|
|
12
|
+
};
|
|
13
|
+
}
|
|
14
|
+
export function errorResult(error) {
|
|
15
|
+
return textResult({ error: error instanceof Error ? error.message : String(error) }, true);
|
|
16
|
+
}
|
package/dist/server.d.ts
ADDED
package/dist/server.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { createRequire } from "node:module";
|
|
2
|
+
import { McpServer } from "@modelcontextprotocol/server";
|
|
3
|
+
import { ApplicationClient } from "./client.js";
|
|
4
|
+
import { registerTools } from "./tools.js";
|
|
5
|
+
import { normalizeBaseUrl } from "./utils.js";
|
|
6
|
+
const require = createRequire(import.meta.url);
|
|
7
|
+
const { version } = require("../package.json");
|
|
8
|
+
export function createMcpServer(config = {}) {
|
|
9
|
+
const token = config.token ?? process.env.APP_API_TOKEN;
|
|
10
|
+
if (!token?.trim()) {
|
|
11
|
+
throw new Error("Set APP_API_TOKEN to a scoped service agent token");
|
|
12
|
+
}
|
|
13
|
+
const apiUrl = normalizeBaseUrl(config.apiUrl ?? process.env.APP_API_URL ?? "http://localhost:3000");
|
|
14
|
+
const server = new McpServer({ name: "evrenta-mcp", version });
|
|
15
|
+
registerTools(server, new ApplicationClient(apiUrl, token.trim()));
|
|
16
|
+
return server;
|
|
17
|
+
}
|
package/dist/tools.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { CallToolResult } from "@modelcontextprotocol/server";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import type { ApplicationClient } from "./client.js";
|
|
4
|
+
export type ToolRegistrar = {
|
|
5
|
+
registerTool<S extends z.ZodObject>(name: string, config: {
|
|
6
|
+
description: string;
|
|
7
|
+
inputSchema: S;
|
|
8
|
+
}, callback: (args: z.output<S>) => Promise<CallToolResult>): unknown;
|
|
9
|
+
};
|
|
10
|
+
export declare function registerTools(server: ToolRegistrar, client: ApplicationClient): void;
|
package/dist/tools.js
ADDED
|
@@ -0,0 +1,337 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { errorResult, textResult } from "./result.js";
|
|
4
|
+
import { fileApiPath, queryString, revisionApiPath, textContentType, validateSpacePath, } from "./utils.js";
|
|
5
|
+
const text = z.string().trim().min(1);
|
|
6
|
+
const revision = z.string().regex(/^(?:[\da-f]{40}|"sha256:[\da-f]{64}")$/i);
|
|
7
|
+
const page = z.string().min(2).max(4096);
|
|
8
|
+
const limit = z.number().int().min(1).max(200);
|
|
9
|
+
function json(method, value) {
|
|
10
|
+
return {
|
|
11
|
+
method,
|
|
12
|
+
...(value === undefined ? {} : { body: JSON.stringify(value) }),
|
|
13
|
+
};
|
|
14
|
+
}
|
|
15
|
+
function pathOf(path) {
|
|
16
|
+
return fileApiPath(validateSpacePath(path));
|
|
17
|
+
}
|
|
18
|
+
function revisionOf(path) {
|
|
19
|
+
return revisionApiPath(validateSpacePath(path));
|
|
20
|
+
}
|
|
21
|
+
function content(bytes, contentType) {
|
|
22
|
+
if (textContentType(contentType)) {
|
|
23
|
+
try {
|
|
24
|
+
return {
|
|
25
|
+
encoding: "utf-8",
|
|
26
|
+
content: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
// Some extensions are served with an incorrect content type; preserve the bytes.
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
return { encoding: "base64", content: Buffer.from(bytes).toString("base64") };
|
|
34
|
+
}
|
|
35
|
+
export function registerTools(server, client) {
|
|
36
|
+
const add = (name, description, schema, handler, spaceScoped = true) => {
|
|
37
|
+
const inputSchema = spaceScoped
|
|
38
|
+
? z
|
|
39
|
+
.object({
|
|
40
|
+
...schema.shape,
|
|
41
|
+
spaceId: z
|
|
42
|
+
.string()
|
|
43
|
+
.uuid()
|
|
44
|
+
.optional()
|
|
45
|
+
.describe("Space ID from list_spaces; omit when only one is accessible"),
|
|
46
|
+
})
|
|
47
|
+
.strict()
|
|
48
|
+
: schema;
|
|
49
|
+
server.registerTool(name, {
|
|
50
|
+
description: spaceScoped
|
|
51
|
+
? `${description} If the token can access multiple spaces, call list_spaces and pass the selected spaceId.`
|
|
52
|
+
: description,
|
|
53
|
+
inputSchema,
|
|
54
|
+
}, async (rawArgs) => {
|
|
55
|
+
try {
|
|
56
|
+
if (!spaceScoped) {
|
|
57
|
+
return textResult(await handler(rawArgs));
|
|
58
|
+
}
|
|
59
|
+
const { spaceId, ...args } = rawArgs;
|
|
60
|
+
const selectedSpace = await client.resolveSpace(spaceId);
|
|
61
|
+
return textResult(await client.inSpace(selectedSpace, () => handler(args)));
|
|
62
|
+
}
|
|
63
|
+
catch (error) {
|
|
64
|
+
return errorResult(error);
|
|
65
|
+
}
|
|
66
|
+
});
|
|
67
|
+
};
|
|
68
|
+
add("list_spaces", "List spaces this API token can access, with its effective permissions in each space.", z.object({}).strict(), () => client.spaces(), false);
|
|
69
|
+
add("whoami", "Return the authenticated account, this space's safe metadata, and the token's effective permissions.", z.object({}).strict(), async () => {
|
|
70
|
+
const [accounts, config] = await Promise.all([
|
|
71
|
+
client.json("/api/accounts"),
|
|
72
|
+
client.json("/api/config"),
|
|
73
|
+
]);
|
|
74
|
+
return {
|
|
75
|
+
user: accounts.find((account) => account.me) ?? null,
|
|
76
|
+
space: {
|
|
77
|
+
id: config.spaceId,
|
|
78
|
+
name: config.spaceName,
|
|
79
|
+
indexPage: config.indexPage,
|
|
80
|
+
readOnly: config.readOnly,
|
|
81
|
+
revisions: config.revisions,
|
|
82
|
+
boardAvailable: Boolean(config.boardUrl),
|
|
83
|
+
},
|
|
84
|
+
permissions: config.permissions ?? [],
|
|
85
|
+
};
|
|
86
|
+
});
|
|
87
|
+
add("list_files", "List visible files in the current space with content type, size, and permissions.", z.object({}).strict(), () => client.json("/api/files"));
|
|
88
|
+
add("get_file_metadata", "Read metadata and the current content revision for a file without downloading its contents.", z.object({ path: text }), async ({ path }) => {
|
|
89
|
+
const headers = await client.head(pathOf(path));
|
|
90
|
+
return {
|
|
91
|
+
path,
|
|
92
|
+
contentType: headers.get("x-content-type") ?? headers.get("content-type"),
|
|
93
|
+
size: Number(headers.get("x-content-length") ?? headers.get("content-length")),
|
|
94
|
+
permission: headers.get("x-permission"),
|
|
95
|
+
created: Number(headers.get("x-created")),
|
|
96
|
+
lastModified: Number(headers.get("x-last-modified")),
|
|
97
|
+
revision: headers.get("x-app-revision") ?? headers.get("etag"),
|
|
98
|
+
};
|
|
99
|
+
});
|
|
100
|
+
add("read_file", "Read a file. Text is returned as UTF-8; binary files are returned as base64. Reads are bounded to 2 MiB per call.", z
|
|
101
|
+
.object({
|
|
102
|
+
path: text,
|
|
103
|
+
maxBytes: z
|
|
104
|
+
.number()
|
|
105
|
+
.int()
|
|
106
|
+
.min(1)
|
|
107
|
+
.max(2 * 1024 * 1024)
|
|
108
|
+
.default(256 * 1024),
|
|
109
|
+
})
|
|
110
|
+
.strict(), async ({ path, maxBytes }) => {
|
|
111
|
+
const result = await client.bytes(pathOf(path), maxBytes);
|
|
112
|
+
return {
|
|
113
|
+
path,
|
|
114
|
+
contentType: result.contentType,
|
|
115
|
+
revision: result.headers.get("x-app-revision") ?? result.headers.get("etag"),
|
|
116
|
+
...content(result.bytes, result.contentType),
|
|
117
|
+
};
|
|
118
|
+
});
|
|
119
|
+
add("write_file", "Create or replace a UTF-8 file. Use revision from read_file/get_file_metadata as ifMatch to prevent overwriting concurrent edits; set createOnly for a new file.", z
|
|
120
|
+
.object({
|
|
121
|
+
path: text,
|
|
122
|
+
content: z.string().max(1_000_000),
|
|
123
|
+
contentType: z.string().max(128).optional(),
|
|
124
|
+
ifMatch: revision.optional(),
|
|
125
|
+
createOnly: z.boolean().default(false),
|
|
126
|
+
})
|
|
127
|
+
.strict(), async ({ path, content: value, contentType, ifMatch, createOnly }) => {
|
|
128
|
+
if (ifMatch && createOnly)
|
|
129
|
+
throw new Error("ifMatch and createOnly cannot be used together");
|
|
130
|
+
const headers = new Headers({
|
|
131
|
+
"Content-Type": contentType ??
|
|
132
|
+
(path.endsWith(".md")
|
|
133
|
+
? "text/markdown; charset=utf-8"
|
|
134
|
+
: "text/plain; charset=utf-8"),
|
|
135
|
+
});
|
|
136
|
+
if (ifMatch)
|
|
137
|
+
headers.set("If-Match", ifMatch);
|
|
138
|
+
if (createOnly)
|
|
139
|
+
headers.set("If-None-Match", "*");
|
|
140
|
+
const result = await client.text(pathOf(path), {
|
|
141
|
+
method: "PUT",
|
|
142
|
+
headers,
|
|
143
|
+
body: value,
|
|
144
|
+
});
|
|
145
|
+
return {
|
|
146
|
+
path,
|
|
147
|
+
status: "saved",
|
|
148
|
+
revision: result.headers.get("x-app-revision") ?? result.headers.get("etag"),
|
|
149
|
+
};
|
|
150
|
+
});
|
|
151
|
+
add("reconcile_file", "Apply a UTF-8 edit against the exact base text. The service merges concurrent edits and returns applied, merged, conflicted, or retry; inspect returned text before another write. This is safer than overwriting when another client may be editing.", z
|
|
152
|
+
.object({
|
|
153
|
+
path: text,
|
|
154
|
+
baseText: z.string().max(1_000_000),
|
|
155
|
+
proposedText: z.string().max(1_000_000),
|
|
156
|
+
})
|
|
157
|
+
.strict(), ({ path, baseText, proposedText }) => {
|
|
158
|
+
const hash = (value) => createHash("sha256").update(value, "utf8").digest("hex");
|
|
159
|
+
return client.json(pathOf(path), {
|
|
160
|
+
...json("POST", {
|
|
161
|
+
baseHash: hash(baseText),
|
|
162
|
+
baseText,
|
|
163
|
+
proposedHash: hash(proposedText),
|
|
164
|
+
proposedText,
|
|
165
|
+
}),
|
|
166
|
+
});
|
|
167
|
+
});
|
|
168
|
+
add("delete_file", "Permanently delete a file. Pass ifMatch from its current metadata to avoid deleting a concurrently changed file.", z.object({ path: text, ifMatch: revision.optional() }).strict(), async ({ path, ifMatch }) => {
|
|
169
|
+
const headers = new Headers();
|
|
170
|
+
if (ifMatch)
|
|
171
|
+
headers.set("If-Match", ifMatch);
|
|
172
|
+
await client.text(pathOf(path), { method: "DELETE", headers });
|
|
173
|
+
return { path, status: "deleted" };
|
|
174
|
+
});
|
|
175
|
+
add("lookup_page", "Resolve a Markdown page path to its stable page ID.", z.object({ path: text }).strict(), ({ path }) => client.json(`/api/pages/lookup?${new URLSearchParams({ path })}`));
|
|
176
|
+
add("get_page", "Resolve a stable page ID to its current path.", z.object({ id: text }).strict(), ({ id }) => client.json(`/api/pages/${encodeURIComponent(id)}`));
|
|
177
|
+
add("move_page_identity", "Update a page's stable identity after its Markdown file has already been moved. The destination file must exist. Pass the id/from path from lookup_page; this tool does not move file contents.", z
|
|
178
|
+
.object({
|
|
179
|
+
id: text,
|
|
180
|
+
from: text,
|
|
181
|
+
to: text,
|
|
182
|
+
})
|
|
183
|
+
.strict(), (args) => client.json("/api/pages/move", json("POST", {
|
|
184
|
+
id: args.id,
|
|
185
|
+
from: validateSpacePath(args.from),
|
|
186
|
+
to: validateSpacePath(args.to),
|
|
187
|
+
})));
|
|
188
|
+
add("get_search_status", "Check whether the search index is ready and which query modes are available.", z.object({}).strict(), () => client.json("/api/search/status"));
|
|
189
|
+
add("search", "Search pages and metadata in this space. Results include page, line, excerpt, and match highlights.", z
|
|
190
|
+
.object({
|
|
191
|
+
query: page,
|
|
192
|
+
mode: z.enum(["words", "phrase"]).optional(),
|
|
193
|
+
scope: z.enum(["pages", "meta", "all"]).optional(),
|
|
194
|
+
include: z.array(text.max(1024)).max(100).optional(),
|
|
195
|
+
exclude: z.array(text.max(1024)).max(100).optional(),
|
|
196
|
+
limit: z.number().int().min(1).max(50).optional(),
|
|
197
|
+
})
|
|
198
|
+
.strict(), (args) => client.json("/api/search/query", json("POST", args)));
|
|
199
|
+
add("list_file_revisions", "List a file's managed Git revisions. `before` is a revision cursor; limit is clamped to 200.", z
|
|
200
|
+
.object({
|
|
201
|
+
path: text,
|
|
202
|
+
before: z
|
|
203
|
+
.string()
|
|
204
|
+
.regex(/^[\da-f]{40}$/i)
|
|
205
|
+
.optional(),
|
|
206
|
+
limit: limit.optional(),
|
|
207
|
+
})
|
|
208
|
+
.strict(), ({ path, before, limit: count }) => client.json(`${revisionOf(path)}${queryString({ before, limit: count })}`));
|
|
209
|
+
add("read_file_revision", "Read a previous file revision, or its diff from the parent revision.", z
|
|
210
|
+
.object({
|
|
211
|
+
path: text,
|
|
212
|
+
revision: z.string().regex(/^[\da-f]{40}$/i),
|
|
213
|
+
diff: z.boolean().default(false),
|
|
214
|
+
maxBytes: z
|
|
215
|
+
.number()
|
|
216
|
+
.int()
|
|
217
|
+
.min(1)
|
|
218
|
+
.max(2 * 1024 * 1024)
|
|
219
|
+
.default(256 * 1024),
|
|
220
|
+
})
|
|
221
|
+
.strict(), async ({ path, revision: rev, diff, maxBytes }) => {
|
|
222
|
+
const result = await client.bytes(`${revisionOf(path)}${queryString({ rev, ...(diff ? { format: "diff" } : {}) })}`, maxBytes);
|
|
223
|
+
return {
|
|
224
|
+
path,
|
|
225
|
+
revision: rev,
|
|
226
|
+
...(diff
|
|
227
|
+
? { diff: new TextDecoder().decode(result.bytes) }
|
|
228
|
+
: content(result.bytes, result.contentType)),
|
|
229
|
+
};
|
|
230
|
+
});
|
|
231
|
+
add("get_document_history", "List immutable content snapshots for a Markdown document.", z.object({ path: text }).strict(), ({ path }) => client.json(`/api/revisions/documents/${validateSpacePath(path).split("/").map(encodeURIComponent).join("/")}`));
|
|
232
|
+
add("read_document_version", "Read a stored immutable document version by its snapshot revision.", z
|
|
233
|
+
.object({
|
|
234
|
+
path: text,
|
|
235
|
+
revision: z.string().min(1).max(128),
|
|
236
|
+
maxBytes: z
|
|
237
|
+
.number()
|
|
238
|
+
.int()
|
|
239
|
+
.min(1)
|
|
240
|
+
.max(2 * 1024 * 1024)
|
|
241
|
+
.default(256 * 1024),
|
|
242
|
+
})
|
|
243
|
+
.strict(), async ({ path, revision: rev, maxBytes }) => {
|
|
244
|
+
const versionPath = `/api/revisions/history/${validateSpacePath(path).split("/").map(encodeURIComponent).join("/")}${queryString({ rev })}`;
|
|
245
|
+
const result = await client.bytes(versionPath, maxBytes);
|
|
246
|
+
return {
|
|
247
|
+
path,
|
|
248
|
+
revision: rev,
|
|
249
|
+
...content(result.bytes, result.contentType),
|
|
250
|
+
};
|
|
251
|
+
});
|
|
252
|
+
add("checkpoint_document", "Create a managed content snapshot for a document. Requires revisions.manage.", z.object({ path: text }).strict(), ({ path }) => client.json(`/api/revisions/documents/${validateSpacePath(path).split("/").map(encodeURIComponent).join("/")}`, json("POST")));
|
|
253
|
+
add("list_revision_history", "List the space's stored document history inventory and storage usage.", z.object({}).strict(), () => client.json("/api/revisions/history"));
|
|
254
|
+
add("delete_document_version", "Permanently delete one stored document snapshot. Requires revisions.manage.", z.object({ path: text, revision: z.string().min(1).max(128) }).strict(), async ({ path, revision: rev }) => {
|
|
255
|
+
await client.text(`/api/revisions/history/${validateSpacePath(path).split("/").map(encodeURIComponent).join("/")}${queryString({ rev })}`, { method: "DELETE" });
|
|
256
|
+
return { path, revision: rev, status: "deleted" };
|
|
257
|
+
});
|
|
258
|
+
add("get_revision_log", "Read the managed space-wide Git history, optionally before a revision and filtered by text.", z
|
|
259
|
+
.object({
|
|
260
|
+
before: z
|
|
261
|
+
.string()
|
|
262
|
+
.regex(/^[\da-f]{40}$/i)
|
|
263
|
+
.optional(),
|
|
264
|
+
query: z.string().max(4096).optional(),
|
|
265
|
+
limit: z.number().int().min(1).max(200).optional(),
|
|
266
|
+
})
|
|
267
|
+
.strict(), ({ before, query, limit: count }) => client.json(`/api/revisions/${queryString({ before, q: query, limit: count })}`));
|
|
268
|
+
add("create_revision_snapshot", "Create a managed Git snapshot of the current space contents. Requires revisions.manage.", z.object({}).strict(), () => client.json("/api/revisions/", json("POST")));
|
|
269
|
+
add("get_revision_activity", "Summarize recent managed revision activity by time and top edited files.", z
|
|
270
|
+
.object({
|
|
271
|
+
since: z.number().int().optional(),
|
|
272
|
+
filesSince: z.number().int().optional(),
|
|
273
|
+
top: z.number().int().min(1).max(50).optional(),
|
|
274
|
+
})
|
|
275
|
+
.strict(), ({ since, filesSince, top }) => client.json(`/api/revisions/activity${queryString({ since, filesSince, top })}`));
|
|
276
|
+
add("get_revision_sync_status", "Inspect API-driven repository folder sync without starting a job.", z.object({}).strict(), () => client.json("/api/revisions/sync"));
|
|
277
|
+
add("sync_revisions", "Request an API-driven repository folder sync. The repository wins simultaneous edits. Requires revisions.manage and a configured connection.", z.object({}).strict(), () => client.json("/api/revisions/sync", json("POST")));
|
|
278
|
+
add("get_page_share", "Check whether a Markdown page currently has a public share link.", z.object({ path: text }).strict(), ({ path }) => client.json(`/api/pages/share?${new URLSearchParams({ path })}`));
|
|
279
|
+
add("set_page_share", "Enable or disable a public share link for a Markdown page. Enabling sharing exposes the page to anyone with its link. Requires content.read and content.share.", z.object({ path: text, enabled: z.boolean() }).strict(), ({ path, enabled }) => client.json("/api/pages/share", json("POST", { path, enabled })));
|
|
280
|
+
add("list_drawing_shares", "List existing share links for a drawing. Requires drawing write access.", z.object({ path: text }).strict(), ({ path }) => client.json(`/api/draw/shares?${new URLSearchParams({ path })}`));
|
|
281
|
+
add("create_drawing_share", "Create a time-limited view/edit share for a drawing. The returned bearer link grants access until expiry; treat it as a secret. Requires drawing share permission.", z
|
|
282
|
+
.object({
|
|
283
|
+
path: text,
|
|
284
|
+
access: z.enum(["view", "edit"]),
|
|
285
|
+
expiresIn: z
|
|
286
|
+
.number()
|
|
287
|
+
.int()
|
|
288
|
+
.min(60)
|
|
289
|
+
.max(30 * 24 * 60 * 60),
|
|
290
|
+
})
|
|
291
|
+
.strict(), (args) => client.json("/api/draw/shares", json("POST", args)));
|
|
292
|
+
add("revoke_drawing_share", "Revoke a drawing share by ID. Requires drawing share permission.", z.object({ id: text, path: text }).strict(), async ({ id, path }) => {
|
|
293
|
+
await client.text(`/api/draw/shares/${encodeURIComponent(id)}?${new URLSearchParams({ path })}`, { method: "DELETE" });
|
|
294
|
+
return { id, path, status: "revoked" };
|
|
295
|
+
});
|
|
296
|
+
add("list_board_tasks", "List tasks on the task board linked to this space (page 1–1,000,000; limit up to 100). Requires board.read.", z
|
|
297
|
+
.object({
|
|
298
|
+
page: z.number().int().min(1).max(1_000_000).default(1),
|
|
299
|
+
limit: z.number().int().min(1).max(100).default(100),
|
|
300
|
+
})
|
|
301
|
+
.strict(), ({ page: pageNumber, limit: count }) => client.json(`/api/board/tasks${queryString({ page: pageNumber, limit: count })}`));
|
|
302
|
+
add("create_board_task", "Create a task on the task board linked to this space. Requires board.manage. The optional sourcePage is a path in this space.", z
|
|
303
|
+
.object({
|
|
304
|
+
title: text.max(500),
|
|
305
|
+
description: z
|
|
306
|
+
.string()
|
|
307
|
+
.max(64 * 1024)
|
|
308
|
+
.default(""),
|
|
309
|
+
sourcePage: z.string().max(1024).optional(),
|
|
310
|
+
})
|
|
311
|
+
.strict(), (args) => client.json("/api/board/tasks", json("POST", args)));
|
|
312
|
+
add("update_board_task", "Update a task on the task board linked to this space. Set one or more of status, description, assigneeId, or dueDate; use null to clear the assignee or due date. Requires board.manage.", z
|
|
313
|
+
.object({
|
|
314
|
+
id: text.max(128),
|
|
315
|
+
status: z.string().max(128).optional(),
|
|
316
|
+
description: z
|
|
317
|
+
.string()
|
|
318
|
+
.max(64 * 1024)
|
|
319
|
+
.optional(),
|
|
320
|
+
assigneeId: z.string().trim().min(1).max(128).nullable().optional(),
|
|
321
|
+
dueDate: z.string().max(64).nullable().optional(),
|
|
322
|
+
})
|
|
323
|
+
.strict(), ({ id, ...updates }) => {
|
|
324
|
+
if (!Object.values(updates).some((value) => value !== undefined))
|
|
325
|
+
throw new Error("Provide at least one task field to update");
|
|
326
|
+
return client.json(`/api/board/tasks/${encodeURIComponent(id)}`, {
|
|
327
|
+
...json("PUT", updates),
|
|
328
|
+
});
|
|
329
|
+
});
|
|
330
|
+
add("merge_text", "Three-way merge text with conflict detection. This tool is pure computation and does not change files.", z
|
|
331
|
+
.object({
|
|
332
|
+
base: z.string().max(1_000_000),
|
|
333
|
+
local: z.string().max(1_000_000),
|
|
334
|
+
remote: z.string().max(1_000_000),
|
|
335
|
+
})
|
|
336
|
+
.strict(), (args) => client.json("/api/merges", json("POST", args)));
|
|
337
|
+
}
|
package/dist/utils.d.ts
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export declare function normalizeBaseUrl(raw: string): string;
|
|
2
|
+
export declare function validateSpacePath(path: string): string;
|
|
3
|
+
export declare function fileApiPath(path: string): string;
|
|
4
|
+
export declare function revisionApiPath(path: string): string;
|
|
5
|
+
export declare function queryString(values: Record<string, string | number | undefined>): string;
|
|
6
|
+
export declare function textContentType(contentType: string): boolean;
|
package/dist/utils.js
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
const PATH_LIMIT = 1024;
|
|
2
|
+
function hasControlCharacter(path) {
|
|
3
|
+
for (let index = 0; index < path.length; index++) {
|
|
4
|
+
const code = path.charCodeAt(index);
|
|
5
|
+
if (code < 0x20 || code === 0x7f)
|
|
6
|
+
return true;
|
|
7
|
+
}
|
|
8
|
+
return false;
|
|
9
|
+
}
|
|
10
|
+
export function normalizeBaseUrl(raw) {
|
|
11
|
+
let url;
|
|
12
|
+
try {
|
|
13
|
+
url = new URL(raw.trim());
|
|
14
|
+
}
|
|
15
|
+
catch {
|
|
16
|
+
throw new Error("APP_API_URL must be an absolute HTTP(S) URL");
|
|
17
|
+
}
|
|
18
|
+
if (!["http:", "https:"].includes(url.protocol) ||
|
|
19
|
+
!url.host ||
|
|
20
|
+
url.username ||
|
|
21
|
+
url.password ||
|
|
22
|
+
url.search ||
|
|
23
|
+
url.hash) {
|
|
24
|
+
throw new Error("APP_API_URL must be an HTTP(S) workspace service origin");
|
|
25
|
+
}
|
|
26
|
+
if (url.protocol === "http:" &&
|
|
27
|
+
!["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)) {
|
|
28
|
+
throw new Error("APP_API_URL must use HTTPS except for loopback development");
|
|
29
|
+
}
|
|
30
|
+
const pathname = url.pathname.replace(/\/+$/, "");
|
|
31
|
+
if (pathname && pathname !== "/api") {
|
|
32
|
+
throw new Error("APP_API_URL must be the workspace service origin, without a space path");
|
|
33
|
+
}
|
|
34
|
+
return url.origin;
|
|
35
|
+
}
|
|
36
|
+
export function validateSpacePath(path) {
|
|
37
|
+
if (!path ||
|
|
38
|
+
path.length > PATH_LIMIT ||
|
|
39
|
+
path.startsWith("/") ||
|
|
40
|
+
path.includes("\\") ||
|
|
41
|
+
hasControlCharacter(path) ||
|
|
42
|
+
path
|
|
43
|
+
.split("/")
|
|
44
|
+
.some((part) => !part || part === "." || part === ".." || part.startsWith("."))) {
|
|
45
|
+
throw new Error("path must be a visible relative path inside the selected space");
|
|
46
|
+
}
|
|
47
|
+
return path;
|
|
48
|
+
}
|
|
49
|
+
export function fileApiPath(path) {
|
|
50
|
+
return `/api/files/${validateSpacePath(path)
|
|
51
|
+
.split("/")
|
|
52
|
+
.map(encodeURIComponent)
|
|
53
|
+
.join("/")}`;
|
|
54
|
+
}
|
|
55
|
+
export function revisionApiPath(path) {
|
|
56
|
+
return `/api/revisions/${validateSpacePath(path)
|
|
57
|
+
.split("/")
|
|
58
|
+
.map(encodeURIComponent)
|
|
59
|
+
.join("/")}`;
|
|
60
|
+
}
|
|
61
|
+
export function queryString(values) {
|
|
62
|
+
const query = new URLSearchParams();
|
|
63
|
+
for (const [key, value] of Object.entries(values)) {
|
|
64
|
+
if (value !== undefined)
|
|
65
|
+
query.set(key, String(value));
|
|
66
|
+
}
|
|
67
|
+
const encoded = query.toString();
|
|
68
|
+
return encoded ? `?${encoded}` : "";
|
|
69
|
+
}
|
|
70
|
+
export function textContentType(contentType) {
|
|
71
|
+
return /^(text\/|application\/(?:json|xml|javascript|yaml|x-yaml|toml))/i.test(contentType);
|
|
72
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,79 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@evrenta/mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"mcpName": "io.github.evrenta/mcp",
|
|
5
|
+
"description": "MCP server for workspace pages, search, revisions, sharing, and linked task boards",
|
|
6
|
+
"author": "Stefan Kumarasinghe",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"homepage": "https://www.npmjs.com/package/@evrenta/mcp",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/Evrenta/mcp.git"
|
|
12
|
+
},
|
|
13
|
+
"type": "module",
|
|
14
|
+
"bin": {
|
|
15
|
+
"evrenta-mcp": "dist/index.js"
|
|
16
|
+
},
|
|
17
|
+
"exports": {
|
|
18
|
+
".": {
|
|
19
|
+
"import": "./dist/server.js",
|
|
20
|
+
"types": "./dist/server.d.ts"
|
|
21
|
+
},
|
|
22
|
+
"./tools": {
|
|
23
|
+
"types": "./dist/tools.d.ts",
|
|
24
|
+
"import": "./dist/tools.js"
|
|
25
|
+
},
|
|
26
|
+
"./client": {
|
|
27
|
+
"types": "./dist/client.d.ts",
|
|
28
|
+
"import": "./dist/client.js"
|
|
29
|
+
},
|
|
30
|
+
"./utils": {
|
|
31
|
+
"types": "./dist/utils.d.ts",
|
|
32
|
+
"import": "./dist/utils.js"
|
|
33
|
+
}
|
|
34
|
+
},
|
|
35
|
+
"publishConfig": {
|
|
36
|
+
"access": "public"
|
|
37
|
+
},
|
|
38
|
+
"files": [
|
|
39
|
+
"dist",
|
|
40
|
+
"README.md",
|
|
41
|
+
"LICENSE"
|
|
42
|
+
],
|
|
43
|
+
"engines": {
|
|
44
|
+
"node": ">=24"
|
|
45
|
+
},
|
|
46
|
+
"keywords": [
|
|
47
|
+
"ai-agents",
|
|
48
|
+
"claude",
|
|
49
|
+
"kanban",
|
|
50
|
+
"evrenta",
|
|
51
|
+
"evrenta-mcp",
|
|
52
|
+
"mcp",
|
|
53
|
+
"mcp-server",
|
|
54
|
+
"model-context-protocol",
|
|
55
|
+
"project-management",
|
|
56
|
+
"stdio",
|
|
57
|
+
"tasks"
|
|
58
|
+
],
|
|
59
|
+
"scripts": {
|
|
60
|
+
"build": "tsc -p tsconfig.json",
|
|
61
|
+
"prepublishOnly": "npm run build",
|
|
62
|
+
"dev": "tsx watch src/index.ts",
|
|
63
|
+
"start": "node dist/index.js",
|
|
64
|
+
"test": "vitest run --config vitest.config.ts",
|
|
65
|
+
"test:coverage": "vitest run --config vitest.config.ts --coverage",
|
|
66
|
+
"typecheck": "tsc --noEmit -p tsconfig.json"
|
|
67
|
+
},
|
|
68
|
+
"dependencies": {
|
|
69
|
+
"@modelcontextprotocol/server": "2.4.0",
|
|
70
|
+
"zod": "^4.6.7"
|
|
71
|
+
},
|
|
72
|
+
"devDependencies": {
|
|
73
|
+
"@types/node": "^26.6.2",
|
|
74
|
+
"@vitest/coverage-v8": "4.1.12",
|
|
75
|
+
"tsx": "^4.23.15",
|
|
76
|
+
"typescript": "^7.0.2",
|
|
77
|
+
"vitest": "^4.1.11"
|
|
78
|
+
}
|
|
79
|
+
}
|