@centia-io/mcp-server 1.0.5 → 1.0.7

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.
Files changed (4) hide show
  1. package/README.md +148 -131
  2. package/centia-api.json +3946 -3134
  3. package/dist/index.js +112 -15
  4. package/package.json +33 -32
package/README.md CHANGED
@@ -1,131 +1,148 @@
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
+ ## Authentication
16
+
17
+ The MCP server uses the same login as the [`gc2-cli`](https://www.npmjs.com/package/@mapcentia/gc2-cli):
18
+
19
+ ```bash
20
+ npm i -g @mapcentia/gc2-cli
21
+ gc2 connect https://api.centia.io # only if not the default
22
+ gc2 login # browser, device, or password
23
+ ```
24
+
25
+ The MCP server reads `~/.config/configstore/gc2-env.json` (managed by `gc2-cli`) and refreshes the access token automatically when it expires.
26
+
27
+ For headless / CI use, set `API_TOKEN` (and optionally `API_BASE_URL`) — env vars take precedence over the stored session:
28
+
29
+ - `API_BASE_URL` (optional) — Base URL for the Centia API. Default: `https://api.centia.io`
30
+ - `API_TOKEN` (optional) — Static personal access token. Bypasses the stored `gc2-cli` session.
31
+
32
+ The API surface is defined in `centia-api.json` (already included in the repo). The server reads it at runtime to generate tools.
33
+
34
+ ## Run locally (development)
35
+ Hot‑reload development run with `tsx`:
36
+ ```bash
37
+ npm run dev
38
+ ```
39
+ 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.
40
+
41
+ ## Run with npx
42
+ You can run the server directly using `npx`.
43
+
44
+ If running from the source locally:
45
+ ```bash
46
+ npm run build
47
+ npx .
48
+ ```
49
+
50
+ If the package is installed or you want to use the published version:
51
+ ```bash
52
+ npx @centia/mcp-server
53
+ ```
54
+
55
+ ## Build and run (production)
56
+ ```bash
57
+ npm run build
58
+ npm start
59
+ ```
60
+ This compiles TypeScript to `dist/` and starts `node dist/index.js`.
61
+
62
+ If you prefer a static token over the stored `gc2-cli` session (e.g. CI):
63
+ ```bash
64
+ API_TOKEN=your_token_here npm start
65
+ # or
66
+ API_BASE_URL=https://api.centia.io API_TOKEN=your_token_here npm run dev
67
+ ```
68
+
69
+ ## Using with MCP Inspector (recommended for local testing)
70
+ MCP Inspector lets you connect to the server and try tools interactively.
71
+
72
+ 1. Start the Inspector UI:
73
+ ```bash
74
+ npx @modelcontextprotocol/inspector -- npx @centia/mcp-server
75
+ ```
76
+ 2. If needed, add environment variables in the Inspector connection dialog (e.g., `API_TOKEN`).
77
+
78
+ ## Using with Claude Desktop
79
+ Add the server to your Claude Desktop MCP config (e.g., `claude_desktop_config.json`).
80
+
81
+ ### Using npx (easiest)
82
+ ```json
83
+ {
84
+ "mcpServers": {
85
+ "centia": {
86
+ "command": "npx",
87
+ "args": ["-y", "@centia/mcp-server"]
88
+ }
89
+ }
90
+ }
91
+ ```
92
+
93
+ Run `gc2 login` once and the server will pick up the session. To force a static token instead, add `"env": { "API_TOKEN": "YOUR_CENTIA_TOKEN" }`.
94
+
95
+ ### Using local source
96
+ ```json
97
+ {
98
+ "mcpServers": {
99
+ "centia": {
100
+ "command": "npm",
101
+ "args": ["run", "start"],
102
+ "cwd": "/absolute/path/to/your/mcp-server"
103
+ }
104
+ }
105
+ }
106
+ ```
107
+ - For development, replace `"args": ["run", "start"]` with `"args": ["run", "dev"]`.
108
+ - Ensure `cwd` points to this project directory.
109
+
110
+ ## NPM scripts
111
+ - `npm run dev` — Run TypeScript directly with `tsx` (hot‑reload style dev loop).
112
+ - `npm run build` — Compile TypeScript to CommonJS/ESM in `dist/` via `tsc`.
113
+ - `npm start` — Run the built server (`node dist/index.js`).
114
+
115
+ ## Using AGENTS.md and Skills with AI Coding Agents
116
+ This repository includes an `AGENTS.md` file with global hard rules and a `skills/` folder with task-specific guidance for AI coding agents (like Claude Code, Junie, etc.) when working with Centia BaaS.
117
+
118
+ `AGENTS.md` contains the core rules (tool priority, security baselines, destructive-ops policy), while each skill in `skills/*/SKILL.md` covers a specific workflow area.
119
+
120
+ To ensure your AI agent follows these rules while developing your application:
121
+
122
+ 1. Copy `AGENTS.md` and the `skills/` folder from this repository to the root of **your own application's** repository.
123
+ 2. When starting a session with your AI agent, it will automatically find and follow the guidelines.
124
+
125
+ **AGENTS.md** covers:
126
+ - **Prime Directive**: Preferring MCP tools and official SDKs.
127
+ - **Tool Priority**: Order of interaction (MCP tools > SDK > HTTP).
128
+ - **Security & Auth**: How to handle tokens and OAuth flows correctly.
129
+ - **Destructive Operations Policy**: Requiring explicit confirmation before destructive changes.
130
+
131
+ **Skills** (`skills/*/SKILL.md`) cover task-specific workflows:
132
+ - `centia-runtime-sdk` — Building JS/TS runtime code with `@centia-io/sdk`
133
+ - `centia-provisioning` — Schema, tables, columns, constraints, indexes, migrations
134
+ - `centia-json-rpc` — JSON-RPC method lifecycle and TypeScript interfaces
135
+ - `centia-auth-model` — Auth across browser, backend, CLI, and provisioning
136
+ - `centia-types-formats` — PostgreSQL types, casts, type hints, output formats
137
+ - `centia-file-import` — File import workflow
138
+ - `centia-openapi-docs` — OpenAPI and docs fallback policy
139
+ - `centia-delivery` — Delivery checklist and quality gate
140
+
141
+ ## Troubleshooting
142
+ - Tools missing or inputs look odd: ensure `centia-api.json` exists and is valid. The server generates tools from this file at startup.
143
+ - 401/403 errors: run `gc2 login` (or set a valid `API_TOKEN` in the environment for headless use).
144
+ - 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.
145
+ - ESM/CommonJS issues: this project uses ESM (`"type": "module"`). Use Node.js 18+ and run scripts via npm as shown above.
146
+
147
+ ## License
148
+ ISC