@centia-io/mcp-server 1.0.3 → 1.0.5
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 +131 -131
- package/centia-api.json +3134 -3193
- package/dist/index.js +41 -7
- package/package.json +32 -32
package/README.md
CHANGED
|
@@ -1,131 +1,131 @@
|
|
|
1
|
-
# Centia MCP Server
|
|
2
|
-
|
|
3
|
-
A Model Context Protocol (MCP) server that exposes the Centia API as MCP tools generated from the OpenAPI spec. It communicates over STDIO and can be used with any MCP-compatible client (Claude Desktop, MCP Inspector, etc.).
|
|
4
|
-
|
|
5
|
-
## Prerequisites
|
|
6
|
-
- Node.js 18+ (20+ recommended)
|
|
7
|
-
- npm 9+
|
|
8
|
-
|
|
9
|
-
## Install
|
|
10
|
-
```bash
|
|
11
|
-
# From the project root
|
|
12
|
-
npm install
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
## Configuration
|
|
16
|
-
The server accepts the following environment variables:
|
|
17
|
-
|
|
18
|
-
- `API_BASE_URL` (optional) — Base URL for the Centia API. Default: `https://api.centia.io`
|
|
19
|
-
- `API_TOKEN` (recommended) — Personal access token for Centia. Most endpoints/tools require authentication; set this to enable them.
|
|
20
|
-
|
|
21
|
-
The API surface is defined in `centia-api.json` (already included in the repo). The server reads it at runtime to generate tools.
|
|
22
|
-
|
|
23
|
-
## Run locally (development)
|
|
24
|
-
Hot‑reload development run with `tsx`:
|
|
25
|
-
```bash
|
|
26
|
-
npm run dev
|
|
27
|
-
```
|
|
28
|
-
This starts the MCP server on STDIO. It is meant to be launched by an MCP client (see below), but you can also smoke‑test it with the MCP Inspector.
|
|
29
|
-
|
|
30
|
-
## Run with npx
|
|
31
|
-
You can run the server directly using `npx`.
|
|
32
|
-
|
|
33
|
-
If running from the source locally:
|
|
34
|
-
```bash
|
|
35
|
-
npm run build
|
|
36
|
-
npx .
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
If the package is installed or you want to use the published version:
|
|
40
|
-
```bash
|
|
41
|
-
npx @centia/mcp-server
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
## Build and run (production)
|
|
45
|
-
```bash
|
|
46
|
-
npm run build
|
|
47
|
-
npm start
|
|
48
|
-
```
|
|
49
|
-
This compiles TypeScript to `dist/` and starts `node dist/index.js`.
|
|
50
|
-
|
|
51
|
-
If you need environment variables:
|
|
52
|
-
```bash
|
|
53
|
-
API_TOKEN=your_token_here npm start
|
|
54
|
-
# or
|
|
55
|
-
API_BASE_URL=https://api.centia.io API_TOKEN=your_token_here npm run dev
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
## Using with MCP Inspector (recommended for local testing)
|
|
59
|
-
MCP Inspector lets you connect to the server and try tools interactively.
|
|
60
|
-
|
|
61
|
-
1. Start the Inspector UI:
|
|
62
|
-
```bash
|
|
63
|
-
npx @modelcontextprotocol/inspector -- npx @centia/mcp-server
|
|
64
|
-
```
|
|
65
|
-
2. If needed, add environment variables in the Inspector connection dialog (e.g., `API_TOKEN`).
|
|
66
|
-
|
|
67
|
-
## Using with Claude Desktop
|
|
68
|
-
Add the server to your Claude Desktop MCP config (e.g., `claude_desktop_config.json`).
|
|
69
|
-
|
|
70
|
-
### Using npx (easiest)
|
|
71
|
-
```json
|
|
72
|
-
{
|
|
73
|
-
"mcpServers": {
|
|
74
|
-
"centia": {
|
|
75
|
-
"command": "npx",
|
|
76
|
-
"args": ["-y", "@centia/mcp-server"],
|
|
77
|
-
"env": {
|
|
78
|
-
"API_TOKEN": "YOUR_CENTIA_TOKEN",
|
|
79
|
-
"API_BASE_URL": "https://api.centia.io"
|
|
80
|
-
}
|
|
81
|
-
}
|
|
82
|
-
}
|
|
83
|
-
}
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
### Using local source
|
|
87
|
-
```json
|
|
88
|
-
{
|
|
89
|
-
"mcpServers": {
|
|
90
|
-
"centia": {
|
|
91
|
-
"command": "npm",
|
|
92
|
-
"args": ["run", "start"],
|
|
93
|
-
"env": {
|
|
94
|
-
"API_TOKEN": "YOUR_CENTIA_TOKEN",
|
|
95
|
-
"API_BASE_URL": "https://api.centia.io"
|
|
96
|
-
},
|
|
97
|
-
"cwd": "/absolute/path/to/your/mcp-server"
|
|
98
|
-
}
|
|
99
|
-
}
|
|
100
|
-
}
|
|
101
|
-
```
|
|
102
|
-
- For development, replace `"args": ["run", "start"]` with `"args": ["run", "dev"]`.
|
|
103
|
-
- Ensure `cwd` points to this project directory.
|
|
104
|
-
|
|
105
|
-
## NPM scripts
|
|
106
|
-
- `npm run dev` — Run TypeScript directly with `tsx` (hot‑reload style dev loop).
|
|
107
|
-
- `npm run build` — Compile TypeScript to CommonJS/ESM in `dist/` via `tsc`.
|
|
108
|
-
- `npm start` — Run the built server (`node dist/index.js`).
|
|
109
|
-
|
|
110
|
-
## Using AGENT.md with AI Coding Agents
|
|
111
|
-
This repository includes an `AGENT.md` file that provides specific instructions and best practices for AI coding agents (like Claude Code, Junie, etc.) when working with Centia BaaS.
|
|
112
|
-
|
|
113
|
-
To ensure your AI agent follows these rules while developing your application:
|
|
114
|
-
|
|
115
|
-
1. Copy the `AGENT.md` file from this repository to the root or `src/` folder of **your own application's** repository.
|
|
116
|
-
2. When starting a session with your AI agent, it will automatically find and follow the guidelines defined in `AGENT.md`.
|
|
117
|
-
|
|
118
|
-
The guide covers:
|
|
119
|
-
- **Prime Directive**: Preferring MCP tools and official SDKs.
|
|
120
|
-
- **Tool Priority**: Order of interaction (MCP tools > SDK > HTTP).
|
|
121
|
-
- **Project Structure**: Recommended layout for Centia-based apps.
|
|
122
|
-
- **Security & Auth**: How to handle tokens and OAuth flows correctly.
|
|
123
|
-
|
|
124
|
-
## Troubleshooting
|
|
125
|
-
- Tools missing or inputs look odd: ensure `centia-api.json` exists and is valid. The server generates tools from this file at startup.
|
|
126
|
-
- 401/403 errors: set a valid `API_TOKEN` in the environment.
|
|
127
|
-
- JSON Schema validation errors: schemas are auto‑normalized/sanitized for MCP, but if you updated `centia-api.json`, re-run and check logs for details.
|
|
128
|
-
- ESM/CommonJS issues: this project uses ESM (`"type": "module"`). Use Node.js 18+ and run scripts via npm as shown above.
|
|
129
|
-
|
|
130
|
-
## License
|
|
131
|
-
ISC
|
|
1
|
+
# Centia MCP Server
|
|
2
|
+
|
|
3
|
+
A Model Context Protocol (MCP) server that exposes the Centia API as MCP tools generated from the OpenAPI spec. It communicates over STDIO and can be used with any MCP-compatible client (Claude Desktop, MCP Inspector, etc.).
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
- Node.js 18+ (20+ recommended)
|
|
7
|
+
- npm 9+
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
```bash
|
|
11
|
+
# From the project root
|
|
12
|
+
npm install
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Configuration
|
|
16
|
+
The server accepts the following environment variables:
|
|
17
|
+
|
|
18
|
+
- `API_BASE_URL` (optional) — Base URL for the Centia API. Default: `https://api.centia.io`
|
|
19
|
+
- `API_TOKEN` (recommended) — Personal access token for Centia. Most endpoints/tools require authentication; set this to enable them.
|
|
20
|
+
|
|
21
|
+
The API surface is defined in `centia-api.json` (already included in the repo). The server reads it at runtime to generate tools.
|
|
22
|
+
|
|
23
|
+
## Run locally (development)
|
|
24
|
+
Hot‑reload development run with `tsx`:
|
|
25
|
+
```bash
|
|
26
|
+
npm run dev
|
|
27
|
+
```
|
|
28
|
+
This starts the MCP server on STDIO. It is meant to be launched by an MCP client (see below), but you can also smoke‑test it with the MCP Inspector.
|
|
29
|
+
|
|
30
|
+
## Run with npx
|
|
31
|
+
You can run the server directly using `npx`.
|
|
32
|
+
|
|
33
|
+
If running from the source locally:
|
|
34
|
+
```bash
|
|
35
|
+
npm run build
|
|
36
|
+
npx .
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
If the package is installed or you want to use the published version:
|
|
40
|
+
```bash
|
|
41
|
+
npx @centia/mcp-server
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Build and run (production)
|
|
45
|
+
```bash
|
|
46
|
+
npm run build
|
|
47
|
+
npm start
|
|
48
|
+
```
|
|
49
|
+
This compiles TypeScript to `dist/` and starts `node dist/index.js`.
|
|
50
|
+
|
|
51
|
+
If you need environment variables:
|
|
52
|
+
```bash
|
|
53
|
+
API_TOKEN=your_token_here npm start
|
|
54
|
+
# or
|
|
55
|
+
API_BASE_URL=https://api.centia.io API_TOKEN=your_token_here npm run dev
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Using with MCP Inspector (recommended for local testing)
|
|
59
|
+
MCP Inspector lets you connect to the server and try tools interactively.
|
|
60
|
+
|
|
61
|
+
1. Start the Inspector UI:
|
|
62
|
+
```bash
|
|
63
|
+
npx @modelcontextprotocol/inspector -- npx @centia/mcp-server
|
|
64
|
+
```
|
|
65
|
+
2. If needed, add environment variables in the Inspector connection dialog (e.g., `API_TOKEN`).
|
|
66
|
+
|
|
67
|
+
## Using with Claude Desktop
|
|
68
|
+
Add the server to your Claude Desktop MCP config (e.g., `claude_desktop_config.json`).
|
|
69
|
+
|
|
70
|
+
### Using npx (easiest)
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"mcpServers": {
|
|
74
|
+
"centia": {
|
|
75
|
+
"command": "npx",
|
|
76
|
+
"args": ["-y", "@centia/mcp-server"],
|
|
77
|
+
"env": {
|
|
78
|
+
"API_TOKEN": "YOUR_CENTIA_TOKEN",
|
|
79
|
+
"API_BASE_URL": "https://api.centia.io"
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Using local source
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"mcpServers": {
|
|
90
|
+
"centia": {
|
|
91
|
+
"command": "npm",
|
|
92
|
+
"args": ["run", "start"],
|
|
93
|
+
"env": {
|
|
94
|
+
"API_TOKEN": "YOUR_CENTIA_TOKEN",
|
|
95
|
+
"API_BASE_URL": "https://api.centia.io"
|
|
96
|
+
},
|
|
97
|
+
"cwd": "/absolute/path/to/your/mcp-server"
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
- For development, replace `"args": ["run", "start"]` with `"args": ["run", "dev"]`.
|
|
103
|
+
- Ensure `cwd` points to this project directory.
|
|
104
|
+
|
|
105
|
+
## NPM scripts
|
|
106
|
+
- `npm run dev` — Run TypeScript directly with `tsx` (hot‑reload style dev loop).
|
|
107
|
+
- `npm run build` — Compile TypeScript to CommonJS/ESM in `dist/` via `tsc`.
|
|
108
|
+
- `npm start` — Run the built server (`node dist/index.js`).
|
|
109
|
+
|
|
110
|
+
## Using AGENT.md with AI Coding Agents
|
|
111
|
+
This repository includes an `AGENT.md` file that provides specific instructions and best practices for AI coding agents (like Claude Code, Junie, etc.) when working with Centia BaaS.
|
|
112
|
+
|
|
113
|
+
To ensure your AI agent follows these rules while developing your application:
|
|
114
|
+
|
|
115
|
+
1. Copy the `AGENT.md` file from this repository to the root or `src/` folder of **your own application's** repository.
|
|
116
|
+
2. When starting a session with your AI agent, it will automatically find and follow the guidelines defined in `AGENT.md`.
|
|
117
|
+
|
|
118
|
+
The guide covers:
|
|
119
|
+
- **Prime Directive**: Preferring MCP tools and official SDKs.
|
|
120
|
+
- **Tool Priority**: Order of interaction (MCP tools > SDK > HTTP).
|
|
121
|
+
- **Project Structure**: Recommended layout for Centia-based apps.
|
|
122
|
+
- **Security & Auth**: How to handle tokens and OAuth flows correctly.
|
|
123
|
+
|
|
124
|
+
## Troubleshooting
|
|
125
|
+
- Tools missing or inputs look odd: ensure `centia-api.json` exists and is valid. The server generates tools from this file at startup.
|
|
126
|
+
- 401/403 errors: set a valid `API_TOKEN` in the environment.
|
|
127
|
+
- JSON Schema validation errors: schemas are auto‑normalized/sanitized for MCP, but if you updated `centia-api.json`, re-run and check logs for details.
|
|
128
|
+
- ESM/CommonJS issues: this project uses ESM (`"type": "module"`). Use Node.js 18+ and run scripts via npm as shown above.
|
|
129
|
+
|
|
130
|
+
## License
|
|
131
|
+
ISC
|