mcp-sentinel-qa 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.
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Sentinel API Client
3
+ *
4
+ * HTTP client for the MCP server to communicate with Sentinel API routes.
5
+ * Uses SENTINEL_API_URL and SENTINEL_API_KEY from environment.
6
+ */
7
+ interface ApiResponse<T = unknown> {
8
+ data?: T;
9
+ error?: string;
10
+ details?: unknown;
11
+ pagination?: {
12
+ total: number;
13
+ page: number;
14
+ page_size: number;
15
+ total_pages: number;
16
+ };
17
+ }
18
+ declare class ApiError extends Error {
19
+ readonly status: number;
20
+ readonly details?: unknown | undefined;
21
+ constructor(message: string, status: number, details?: unknown | undefined);
22
+ }
23
+ export declare function get<T = unknown>(path: string, params?: Record<string, string | undefined>): Promise<ApiResponse<T>>;
24
+ export declare function post<T = unknown>(path: string, body: unknown): Promise<ApiResponse<T>>;
25
+ export declare function patch<T = unknown>(path: string, body: unknown): Promise<ApiResponse<T>>;
26
+ export declare function del<T = unknown>(path: string): Promise<ApiResponse<T>>;
27
+ export { ApiError };
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Sentinel API Client
3
+ *
4
+ * HTTP client for the MCP server to communicate with Sentinel API routes.
5
+ * Uses SENTINEL_API_URL and SENTINEL_API_KEY from environment.
6
+ */
7
+ const API_URL = 'https://sentinel-qa.vercel.app';
8
+ const API_KEY = process.env.SENTINEL_API_KEY || '';
9
+ class ApiError extends Error {
10
+ status;
11
+ details;
12
+ constructor(message, status, details) {
13
+ super(message);
14
+ this.status = status;
15
+ this.details = details;
16
+ this.name = 'ApiError';
17
+ }
18
+ }
19
+ function headers() {
20
+ return {
21
+ Authorization: `Bearer ${API_KEY}`,
22
+ 'Content-Type': 'application/json',
23
+ };
24
+ }
25
+ async function handleResponse(response) {
26
+ const body = await response.json();
27
+ if (!response.ok) {
28
+ throw new ApiError(body.error || `HTTP ${response.status}`, response.status, body.details);
29
+ }
30
+ return body;
31
+ }
32
+ export async function get(path, params) {
33
+ const url = new URL(path, API_URL);
34
+ if (params) {
35
+ for (const [key, value] of Object.entries(params)) {
36
+ if (value !== undefined)
37
+ url.searchParams.set(key, value);
38
+ }
39
+ }
40
+ const response = await fetch(url.toString(), { method: 'GET', headers: headers() });
41
+ return handleResponse(response);
42
+ }
43
+ export async function post(path, body) {
44
+ const url = new URL(path, API_URL);
45
+ const response = await fetch(url.toString(), {
46
+ method: 'POST',
47
+ headers: headers(),
48
+ body: JSON.stringify(body),
49
+ });
50
+ return handleResponse(response);
51
+ }
52
+ export async function patch(path, body) {
53
+ const url = new URL(path, API_URL);
54
+ const response = await fetch(url.toString(), {
55
+ method: 'PATCH',
56
+ headers: headers(),
57
+ body: JSON.stringify(body),
58
+ });
59
+ return handleResponse(response);
60
+ }
61
+ export async function del(path) {
62
+ const url = new URL(path, API_URL);
63
+ const response = await fetch(url.toString(), { method: 'DELETE', headers: headers() });
64
+ return handleResponse(response);
65
+ }
66
+ export { ApiError };
@@ -0,0 +1,10 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Sentinel MCP Server
4
+ *
5
+ * Stdio-based MCP server for managing Sentinel test cases from any AI assistant.
6
+ *
7
+ * Usage:
8
+ * SENTINEL_API_KEY=stl_xxx npx mcp-server-sentinel
9
+ */
10
+ export {};
package/dist/server.js ADDED
@@ -0,0 +1,19 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Sentinel MCP Server
4
+ *
5
+ * Stdio-based MCP server for managing Sentinel test cases from any AI assistant.
6
+ *
7
+ * Usage:
8
+ * SENTINEL_API_KEY=stl_xxx npx mcp-server-sentinel
9
+ */
10
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
11
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
12
+ import { registerTestCaseTools } from './tools/test-cases.js';
13
+ const server = new McpServer({
14
+ name: 'sentinel',
15
+ version: '1.0.0',
16
+ });
17
+ registerTestCaseTools(server);
18
+ const transport = new StdioServerTransport();
19
+ await server.connect(transport);
@@ -0,0 +1,7 @@
1
+ /**
2
+ * MCP Tools — Test Cases
3
+ *
4
+ * Tool definitions for managing Sentinel test cases via MCP.
5
+ */
6
+ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
7
+ export declare function registerTestCaseTools(server: McpServer): void;
@@ -0,0 +1,251 @@
1
+ /**
2
+ * MCP Tools — Test Cases
3
+ *
4
+ * Tool definitions for managing Sentinel test cases via MCP.
5
+ */
6
+ import { z } from 'zod';
7
+ import * as api from '../lib/api-client.js';
8
+ export function registerTestCaseTools(server) {
9
+ // =========================================================================
10
+ // sentinel_list_projects
11
+ // =========================================================================
12
+ server.tool('sentinel_list_projects', 'List all projects in the Sentinel workspace. Use this first to get project IDs.', {}, async () => {
13
+ try {
14
+ const result = await api.get('/api/mcp/projects');
15
+ return { content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }] };
16
+ }
17
+ catch (error) {
18
+ return errorResult(error);
19
+ }
20
+ });
21
+ // =========================================================================
22
+ // sentinel_list_functionalities
23
+ // =========================================================================
24
+ server.tool('sentinel_list_functionalities', 'List functionalities (modules/features) for a project. Needed to get functionality_id when creating test cases.', { project_id: z.string().uuid().describe('Project UUID') }, async ({ project_id }) => {
25
+ try {
26
+ const result = await api.get('/api/mcp/functionalities', { project_id });
27
+ return { content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }] };
28
+ }
29
+ catch (error) {
30
+ return errorResult(error);
31
+ }
32
+ });
33
+ // =========================================================================
34
+ // sentinel_create_functionality
35
+ // =========================================================================
36
+ server.tool('sentinel_create_functionality', 'Create a new functionality (module/feature) in a project. Needed before creating test cases if no functionality exists yet.', {
37
+ project_id: z.string().uuid().describe('Project UUID (required)'),
38
+ name: z.string().min(2).max(200).describe('Functionality name (min 2 chars)'),
39
+ status: z.enum(['Ativa', 'Inativa']).default('Ativa').describe('Status (default: Ativa)'),
40
+ description: z.string().optional().describe('Optional description'),
41
+ color: z
42
+ .string()
43
+ .regex(/^#[0-9A-Fa-f]{6}$/)
44
+ .optional()
45
+ .describe('Hex color code (e.g. #3B82F6)'),
46
+ }, async (params) => {
47
+ try {
48
+ const result = await api.post('/api/mcp/functionalities', params);
49
+ return {
50
+ content: [
51
+ {
52
+ type: 'text',
53
+ text: `Functionality created successfully!\n${JSON.stringify(result.data, null, 2)}`,
54
+ },
55
+ ],
56
+ };
57
+ }
58
+ catch (error) {
59
+ return errorResult(error);
60
+ }
61
+ });
62
+ // =========================================================================
63
+ // sentinel_list_test_cases
64
+ // =========================================================================
65
+ server.tool('sentinel_list_test_cases', 'List and search test cases in Sentinel. Supports filtering by project, functionality, priority, status, type, and free-text search (searches title, CT_ID, gherkin, and notes).', {
66
+ project_id: z.string().uuid().optional().describe('Filter by project UUID'),
67
+ functionality_id: z.string().uuid().optional().describe('Filter by functionality UUID'),
68
+ search: z.string().optional().describe('Search in title, CT_ID, gherkin, and notes'),
69
+ priority: z.enum(['Baixa', 'Média', 'Alta']).optional().describe('Filter by priority'),
70
+ test_status: z.enum(['Automatizado', 'Manual']).optional().describe('Filter by test status'),
71
+ scenario_status: z
72
+ .enum(['Ativo', 'Inativo', 'Descontinuado'])
73
+ .optional()
74
+ .describe('Filter by scenario status'),
75
+ scenario_type: z
76
+ .enum(['Positivo', 'Negativo'])
77
+ .optional()
78
+ .describe('Filter by scenario type'),
79
+ sort_by: z
80
+ .enum(['created_at', 'updated_at', 'title', 'priority', 'ct_id'])
81
+ .optional()
82
+ .describe('Sort field (default: created_at)'),
83
+ sort_order: z.enum(['asc', 'desc']).optional().describe('Sort direction (default: asc)'),
84
+ page: z.number().int().min(1).optional().describe('Page number (default: 1)'),
85
+ page_size: z
86
+ .number()
87
+ .int()
88
+ .min(1)
89
+ .max(100)
90
+ .optional()
91
+ .describe('Items per page (default: 20, max: 100)'),
92
+ }, async (params) => {
93
+ try {
94
+ const queryParams = {};
95
+ if (params.project_id)
96
+ queryParams.project_id = params.project_id;
97
+ if (params.functionality_id)
98
+ queryParams.functionality_id = params.functionality_id;
99
+ if (params.search)
100
+ queryParams.search = params.search;
101
+ if (params.priority)
102
+ queryParams.priority = params.priority;
103
+ if (params.test_status)
104
+ queryParams.test_status = params.test_status;
105
+ if (params.scenario_status)
106
+ queryParams.scenario_status = params.scenario_status;
107
+ if (params.scenario_type)
108
+ queryParams.scenario_type = params.scenario_type;
109
+ if (params.sort_by)
110
+ queryParams.sort_by = params.sort_by;
111
+ if (params.sort_order)
112
+ queryParams.sort_order = params.sort_order;
113
+ if (params.page)
114
+ queryParams.page = String(params.page);
115
+ if (params.page_size)
116
+ queryParams.page_size = String(params.page_size);
117
+ const result = await api.get('/api/mcp/test-cases', queryParams);
118
+ return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
119
+ }
120
+ catch (error) {
121
+ return errorResult(error);
122
+ }
123
+ });
124
+ // =========================================================================
125
+ // sentinel_get_test_case
126
+ // =========================================================================
127
+ server.tool('sentinel_get_test_case', 'Get detailed information about a specific test case by ID.', { id: z.string().uuid().describe('Test case UUID') }, async ({ id }) => {
128
+ try {
129
+ const result = await api.get(`/api/mcp/test-cases/${id}`);
130
+ return { content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }] };
131
+ }
132
+ catch (error) {
133
+ return errorResult(error);
134
+ }
135
+ });
136
+ // =========================================================================
137
+ // sentinel_create_test_case
138
+ // =========================================================================
139
+ server.tool('sentinel_create_test_case', 'Create a new test case in Sentinel. Requires project_id (use sentinel_list_projects first). Use sentinel_list_functionalities to get functionality_id.', {
140
+ project_id: z.string().uuid().describe('Project UUID (required)'),
141
+ functionality_id: z.string().uuid().optional().describe('Functionality UUID (optional)'),
142
+ title: z.string().min(5).max(500).describe('Test case title (min 5 chars)'),
143
+ scenario_type: z.enum(['Positivo', 'Negativo']).describe('Scenario type'),
144
+ gherkin: z.string().min(1).describe('Gherkin/BDD scenario text'),
145
+ priority: z.enum(['Baixa', 'Média', 'Alta']).describe('Priority level'),
146
+ test_status: z.enum(['Automatizado', 'Manual']).describe('Test status'),
147
+ should_automate: z.boolean().describe('Whether this test should be automated'),
148
+ platforms: z
149
+ .array(z.enum(['Desktop', 'Mobile', 'API']))
150
+ .min(1)
151
+ .describe('Target platforms (at least one)'),
152
+ scenario_status: z
153
+ .enum(['Ativo', 'Inativo', 'Descontinuado'])
154
+ .default('Ativo')
155
+ .describe('Scenario status (default: Ativo)'),
156
+ notes: z.string().optional().describe('Additional notes'),
157
+ assigned_to: z.string().uuid().optional().describe('User UUID to assign the test case to'),
158
+ }, async (params) => {
159
+ try {
160
+ const result = await api.post('/api/mcp/test-cases', params);
161
+ return {
162
+ content: [
163
+ {
164
+ type: 'text',
165
+ text: `Test case created successfully!\n${JSON.stringify(result, null, 2)}`,
166
+ },
167
+ ],
168
+ };
169
+ }
170
+ catch (error) {
171
+ return errorResult(error);
172
+ }
173
+ });
174
+ // =========================================================================
175
+ // sentinel_update_test_case
176
+ // =========================================================================
177
+ server.tool('sentinel_update_test_case', 'Update an existing test case. Supports partial updates — only provided fields will be changed. Use sentinel_get_test_case first to see current values.', {
178
+ id: z.string().uuid().describe('Test case UUID to update'),
179
+ project_id: z.string().uuid().optional().describe('Project UUID'),
180
+ functionality_id: z
181
+ .string()
182
+ .uuid()
183
+ .optional()
184
+ .nullable()
185
+ .describe('Functionality UUID (null to remove)'),
186
+ title: z.string().min(5).max(500).optional().describe('Test case title'),
187
+ scenario_type: z.enum(['Positivo', 'Negativo']).optional().describe('Scenario type'),
188
+ gherkin: z.string().min(1).optional().describe('Gherkin/BDD scenario text'),
189
+ priority: z.enum(['Baixa', 'Média', 'Alta']).optional().describe('Priority level'),
190
+ test_status: z.enum(['Automatizado', 'Manual']).optional().describe('Test status'),
191
+ should_automate: z.boolean().optional().describe('Whether this test should be automated'),
192
+ platforms: z
193
+ .array(z.enum(['Desktop', 'Mobile', 'API']))
194
+ .min(1)
195
+ .optional()
196
+ .describe('Target platforms'),
197
+ scenario_status: z
198
+ .enum(['Ativo', 'Inativo', 'Descontinuado'])
199
+ .optional()
200
+ .describe('Scenario status'),
201
+ notes: z.string().optional().nullable().describe('Additional notes (null to remove)'),
202
+ assigned_to: z
203
+ .string()
204
+ .uuid()
205
+ .optional()
206
+ .nullable()
207
+ .describe('User UUID to assign (null to unassign)'),
208
+ }, async ({ id, ...body }) => {
209
+ try {
210
+ const result = await api.patch(`/api/mcp/test-cases/${id}`, body);
211
+ return {
212
+ content: [
213
+ {
214
+ type: 'text',
215
+ text: `Test case updated successfully!\n${JSON.stringify(result.data, null, 2)}`,
216
+ },
217
+ ],
218
+ };
219
+ }
220
+ catch (error) {
221
+ return errorResult(error);
222
+ }
223
+ });
224
+ // =========================================================================
225
+ // sentinel_delete_test_case
226
+ // =========================================================================
227
+ server.tool('sentinel_delete_test_case', 'Delete a test case by ID. This action is irreversible. Requires test_cases.delete permission.', { id: z.string().uuid().describe('Test case UUID to delete') }, async ({ id }) => {
228
+ try {
229
+ const result = await api.del(`/api/mcp/test-cases/${id}`);
230
+ return {
231
+ content: [
232
+ {
233
+ type: 'text',
234
+ text: `Test case deleted successfully!\n${JSON.stringify(result.data, null, 2)}`,
235
+ },
236
+ ],
237
+ };
238
+ }
239
+ catch (error) {
240
+ return errorResult(error);
241
+ }
242
+ });
243
+ }
244
+ function errorResult(error) {
245
+ const message = error instanceof api.ApiError
246
+ ? `Error ${error.status}: ${error.message}${error.details ? `\nDetails: ${JSON.stringify(error.details)}` : ''}`
247
+ : error instanceof Error
248
+ ? error.message
249
+ : String(error);
250
+ return { content: [{ type: 'text', text: message }], isError: true };
251
+ }
package/package.json ADDED
@@ -0,0 +1,29 @@
1
+ {
2
+ "name": "mcp-sentinel-qa",
3
+ "version": "1.0.0",
4
+ "description": "MCP server for Sentinel QA — manage test cases from any AI assistant",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "bin": {
8
+ "mcp-sentinel-qa": "dist/server.js"
9
+ },
10
+ "files": ["dist"],
11
+ "scripts": {
12
+ "build": "tsc",
13
+ "dev": "tsx server.ts",
14
+ "prepublishOnly": "tsc"
15
+ },
16
+ "keywords": ["mcp", "sentinel", "qa", "testing", "test-cases"],
17
+ "homepage": "https://sentinel-qa.vercel.app",
18
+ "dependencies": {
19
+ "@modelcontextprotocol/sdk": "^1.12.1",
20
+ "zod": "^3.24.4"
21
+ },
22
+ "devDependencies": {
23
+ "typescript": "^5.9.0",
24
+ "tsx": "^4.19.4"
25
+ },
26
+ "engines": {
27
+ "node": ">=18"
28
+ }
29
+ }