mcp-sentinel-qa 1.0.0 → 2.0.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/CHANGELOG.md ADDED
@@ -0,0 +1,56 @@
1
+ # Changelog
2
+
3
+ ## 2.0.1 — 2026-10-29
4
+
5
+ ### Functionality management
6
+
7
+ - Prepare detail, partial update, delete, hierarchy move and test-case transfer
8
+ tools, bringing the source implementation to thirteen tools. Extend existing
9
+ functionality listing with pagination and parent details, and persist the
10
+ parent when creating a functionality.
11
+ - Support root/child hierarchy only, with same-project parents and validation
12
+ against cycles, self-parenting and moving a node with children under a parent.
13
+ - Preserve test cases on functionality deletion: unlink them or transfer them to
14
+ an active target in the same project. Promote direct children to roots rather
15
+ than cascading deletion.
16
+ - Transfer 1–100 unique test cases atomically to an active functionality in the
17
+ same project, enforcing current permissions, workspace and API-key project
18
+ restrictions.
19
+
20
+ These tools use the Sentinel functionality endpoints deployed to production.
21
+ Version 2.0.1 includes the five new tools and the updated functionality listing
22
+ and creation behavior.
23
+
24
+ ## 2.0.0 — 2026-10-28
25
+
26
+ ### Breaking change
27
+
28
+ - Require Node.js 22 or later. Upgrade Node.js before updating an MCP client
29
+ configuration that pins this package. Node.js 18 and 20 are no longer supported.
30
+
31
+ ### Dependencies and security
32
+
33
+ - Replace the combined MCP SDK runtime with the server-only
34
+ `@modelcontextprotocol/server` 2.4.0 or later, removing HTTP-server and
35
+ shell-spawning dependency branches unnecessary for this stdio server.
36
+ - Raise the Zod minimum to 4.6.7, incorporating upstream security fixes, and
37
+ refresh the standalone dependency lockfile. Keep the legacy SDK 1.32.2 or later
38
+ only in development dependencies for client compatibility tests.
39
+ - Add automated checks for compilation, protocol behavior, dependency advisories
40
+ and the distributable package.
41
+
42
+ ### Package documentation and metadata
43
+
44
+ - Include installation, configuration, tool and permission documentation, an MIT
45
+ license and source/issue links in the package.
46
+ - Correct examples to use `mcp-sentinel-qa` and document the fixed production API
47
+ endpoint.
48
+ - Keep the server's reported version aligned with the package version.
49
+
50
+ The stdio transport, `SENTINEL_API_KEY` variable and eight existing tool names are
51
+ preserved.
52
+
53
+ ## 1.0.0
54
+
55
+ - Initial published package for Sentinel projects, functionalities and test cases
56
+ through eight stdio MCP tools.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 João Vitor Matos
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 ADDED
@@ -0,0 +1,152 @@
1
+ # Sentinel QA MCP server
2
+
3
+ [mcp-sentinel-qa](https://www.npmjs.com/package/mcp-sentinel-qa) connects an MCP-compatible
4
+ AI assistant to [Sentinel QA](https://sentinel-qa.vercel.app). Browse projects,
5
+ organize functionalities and manage test cases through the Model Context Protocol.
6
+
7
+ The server runs locally over **stdio** and sends authenticated HTTPS requests to
8
+ the Sentinel API. It does not require direct database access.
9
+
10
+ The runtime uses the server-only `@modelcontextprotocol/server` package. The
11
+ legacy SDK is used only by development tests to check client compatibility.
12
+
13
+ ## Requirements
14
+
15
+ - Node.js **22 or later**. Use a supported LTS release, such as Node.js 24 or 26.
16
+ - [pnpm](https://pnpm.io/installation).
17
+ - A Sentinel API key and access to the projects you intend to use.
18
+ - An MCP client that supports local stdio servers.
19
+
20
+ ## Connect your assistant
21
+
22
+ Create an API key in the **MCP / API Keys** section of your Sentinel profile.
23
+ Add the following server entry to your MCP client's configuration:
24
+
25
+ ```json
26
+ {
27
+ "mcpServers": {
28
+ "sentinel": {
29
+ "command": "pnpm",
30
+ "args": ["dlx", "mcp-sentinel-qa@2.0.1"],
31
+ "env": {
32
+ "SENTINEL_API_KEY": "YOUR_SENTINEL_API_KEY"
33
+ }
34
+ }
35
+ }
36
+ }
37
+ ```
38
+
39
+ Replace the placeholder locally and restart or reconnect your MCP client. Keep the
40
+ configuration containing your key out of version control. If your client supports
41
+ secret storage or environment-variable references, use those instead.
42
+
43
+ For a manual launch, provide the key through your environment and run:
44
+
45
+ ```sh
46
+ pnpm dlx mcp-sentinel-qa@2.0.1
47
+ ```
48
+
49
+ The process waits for MCP messages on stdin; it is not an interactive terminal UI
50
+ or an HTTP server. The API endpoint is currently fixed to
51
+ `https://sentinel-qa.vercel.app`; `SENTINEL_API_URL` is not supported.
52
+
53
+ ## Tools in 2.0.1
54
+
55
+ The package provides thirteen tools:
56
+
57
+ | Tool | Purpose |
58
+ | --- | --- |
59
+ | `sentinel_list_projects` | List projects available to the API key. Start here to obtain project IDs. |
60
+ | `sentinel_list_functionalities` | List project functionalities with pagination and parent details. |
61
+ | `sentinel_create_functionality` | Create a root or child functionality. |
62
+ | `sentinel_get_functionality` | Retrieve a functionality's details, project and parent. |
63
+ | `sentinel_update_functionality` | Partially edit its name, description, color, status or parent. |
64
+ | `sentinel_move_functionality` | Move a functionality under another root or promote it to a root. |
65
+ | `sentinel_delete_functionality` | Delete a functionality while preserving its cases and children. |
66
+ | `sentinel_move_functionality_test_cases` | Atomically transfer selected test cases to another functionality. |
67
+ | `sentinel_list_test_cases` | Search and paginate test cases, with project, functionality, priority, status and type filters. |
68
+ | `sentinel_get_test_case` | Retrieve a test case by UUID. |
69
+ | `sentinel_create_test_case` | Create a test case with Gherkin, priority, platforms and automation details. |
70
+ | `sentinel_update_test_case` | Update only the fields supplied for an existing test case. |
71
+ | `sentinel_delete_test_case` | Permanently delete a test case by UUID. |
72
+
73
+ Tool schemas expose required fields and allowed values. Test-case lists support
74
+ `page` and `page_size` (maximum 100); functionality lists use the same pagination
75
+ with a default page size of 20.
76
+
77
+ Functionalities support a two-level root/child hierarchy. Parents must be roots
78
+ in the same project. A functionality with children cannot become a child, and
79
+ self-parenting or cycles are rejected. Editing preserves omitted fields. Moving
80
+ a functionality changes its parent; moving test cases changes their assignment.
81
+ Deleting a functionality unlinks its cases by default or transfers them to an
82
+ active target when `target_id` is provided. Direct children become roots and keep
83
+ their own cases.
84
+
85
+ Reading functionalities requires `features.view`; creation requires
86
+ `features.create`; edits and hierarchy changes require `features.edit`. Case
87
+ transfers require `features.edit` and `test_cases.edit`. Deletion requires
88
+ `features.delete` and `test_cases.edit`; transferring cases during deletion also
89
+ requires `features.edit` on the destination. Workspace and API-key project
90
+ restrictions apply to every operation.
91
+
92
+ ## Access and authentication
93
+
94
+ `SENTINEL_API_KEY` is sent as an `Authorization: Bearer` header. Sentinel validates
95
+ the key, its workspace and any project restriction, together with the creator's
96
+ current membership and permissions. The MCP server does not grant additional
97
+ access or bypass project restrictions.
98
+
99
+ Environment-variable access and outbound network access are expected capabilities:
100
+ the server reads its API key and calls the Sentinel HTTPS API. A scanner's
101
+ capability label alone does not establish malicious behavior; review the finding
102
+ and the package code together.
103
+
104
+ Reading projects requires `projects.view`. Reading test cases requires
105
+ `test_cases.view`; functionality visibility also respects `features.view`.
106
+ Creating functionalities requires `features.create`. Test-case writes require
107
+ `test_cases.create`, `test_cases.edit` or `test_cases.delete`, respectively.
108
+
109
+ If a tool returns an authentication or permission error, check whether the key is
110
+ expired or revoked, whether its creator still has access, and whether the target
111
+ project is within the key's scope. Revoke a compromised key in Sentinel and
112
+ replace it in your client configuration.
113
+
114
+ ## Upgrade from 1.x
115
+
116
+ Version 2.0.0 introduced the Node.js 22 minimum; Node.js 18 and 20 are not
117
+ supported. Version 2.0.1 keeps that requirement and adds functionality management
118
+ tools while preserving the existing eight tool names. Update a pinned
119
+ `mcp-sentinel-qa@2.0.0` configuration to `mcp-sentinel-qa@2.0.1`, then restart or
120
+ reconnect your MCP client. Older examples using `mcp-server-sentinel` should use
121
+ `mcp-sentinel-qa` instead.
122
+
123
+ ## Development and release checks
124
+
125
+ The MCP package has a standalone lockfile. From the repository root:
126
+
127
+ ```sh
128
+ pnpm --dir mcp --ignore-workspace install --frozen-lockfile
129
+ pnpm --dir mcp --ignore-workspace check
130
+ pnpm --dir mcp --ignore-workspace audit
131
+ pnpm --dir mcp --ignore-workspace run test:package
132
+ ```
133
+
134
+ The checks compile the package, verify types and exercise the MCP protocol using
135
+ test fixtures. Build output is written to `mcp/dist`.
136
+
137
+ Prepare a distribution archive from the package directory:
138
+
139
+ ```sh
140
+ cd mcp
141
+ pnpm --ignore-workspace pack --pack-destination /tmp
142
+ ```
143
+
144
+ Inspect and test the archive before publishing. A release is available to users
145
+ only after it has been published to the registry; third-party security and health
146
+ reports may require another scan to reflect a new version.
147
+
148
+ ## Source, issues and license
149
+
150
+ - [Source code](https://github.com/JVMatos/sentinel/tree/main/mcp)
151
+ - [Report an issue](https://github.com/JVMatos/sentinel/issues)
152
+ - [MIT license](./LICENSE)
@@ -0,0 +1,19 @@
1
+ export declare function errorResult(error: unknown): {
2
+ content: {
3
+ type: "text";
4
+ text: string;
5
+ }[];
6
+ isError: boolean;
7
+ };
8
+ export declare function toolRequest(operation: () => Promise<unknown>): Promise<{
9
+ content: {
10
+ type: "text";
11
+ text: string;
12
+ }[];
13
+ isError: boolean;
14
+ } | {
15
+ content: {
16
+ type: "text";
17
+ text: string;
18
+ }[];
19
+ }>;
@@ -0,0 +1,18 @@
1
+ import { ApiError } from './api-client.js';
2
+ export function errorResult(error) {
3
+ const message = error instanceof ApiError
4
+ ? `Error ${error.status}: ${error.message}${error.details ? `\nDetails: ${JSON.stringify(error.details)}` : ''}`
5
+ : error instanceof Error
6
+ ? error.message
7
+ : String(error);
8
+ return { content: [{ type: 'text', text: message }], isError: true };
9
+ }
10
+ export async function toolRequest(operation) {
11
+ try {
12
+ const result = await operation();
13
+ return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
14
+ }
15
+ catch (error) {
16
+ return errorResult(error);
17
+ }
18
+ }
@@ -0,0 +1,47 @@
1
+ {
2
+ "name": "mcp-sentinel-qa",
3
+ "version": "2.0.1",
4
+ "description": "MCP server for Sentinel QA — manage functionalities and test cases from any AI assistant",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "author": "João Vitor Matos",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/JVMatos/sentinel.git",
11
+ "directory": "mcp"
12
+ },
13
+ "bugs": {
14
+ "url": "https://github.com/JVMatos/sentinel/issues"
15
+ },
16
+ "bin": {
17
+ "mcp-sentinel-qa": "dist/server.js"
18
+ },
19
+ "files": ["dist", "CHANGELOG.md"],
20
+ "scripts": {
21
+ "build": "tsc",
22
+ "type-check": "tsc --noEmit",
23
+ "test": "node --test tests/*.test.mjs && MCP_TEST_CLIENT=modern node --test tests/*.test.mjs",
24
+ "test:package": "node scripts/verify-package.mjs",
25
+ "check": "pnpm --ignore-workspace run type-check && pnpm --ignore-workspace run build && pnpm --ignore-workspace run test",
26
+ "dev": "tsx server.ts",
27
+ "prepack": "pnpm --ignore-workspace run check",
28
+ "prepublishOnly": "pnpm --ignore-workspace audit --prod"
29
+ },
30
+ "keywords": ["mcp", "sentinel", "qa", "testing", "functionalities", "test-cases"],
31
+ "homepage": "https://sentinel-qa.vercel.app",
32
+ "dependencies": {
33
+ "@modelcontextprotocol/server": "^2.4.0",
34
+ "zod": "^4.6.7"
35
+ },
36
+ "devDependencies": {
37
+ "@modelcontextprotocol/client": "^2.4.0",
38
+ "@modelcontextprotocol/sdk": "^1.32.2",
39
+ "@types/node": "^22.20.5",
40
+ "tsx": "^4.23.15",
41
+ "typescript": "~5.9.3"
42
+ },
43
+ "engines": {
44
+ "node": ">=22"
45
+ },
46
+ "packageManager": "pnpm@11.20.0"
47
+ }
package/dist/server.d.ts CHANGED
@@ -5,6 +5,6 @@
5
5
  * Stdio-based MCP server for managing Sentinel test cases from any AI assistant.
6
6
  *
7
7
  * Usage:
8
- * SENTINEL_API_KEY=stl_xxx npx mcp-server-sentinel
8
+ * SENTINEL_API_KEY=<your-api-key> pnpm dlx mcp-sentinel-qa
9
9
  */
10
10
  export {};
package/dist/server.js CHANGED
@@ -5,15 +5,16 @@
5
5
  * Stdio-based MCP server for managing Sentinel test cases from any AI assistant.
6
6
  *
7
7
  * Usage:
8
- * SENTINEL_API_KEY=stl_xxx npx mcp-server-sentinel
8
+ * SENTINEL_API_KEY=<your-api-key> pnpm dlx mcp-sentinel-qa
9
9
  */
10
- import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
11
- import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
10
+ import { McpServer } from '@modelcontextprotocol/server';
11
+ import { serveStdio } from '@modelcontextprotocol/server/stdio';
12
+ import metadata from './package.json' with { type: 'json' };
13
+ import { registerFunctionalityTools } from './tools/functionalities.js';
12
14
  import { registerTestCaseTools } from './tools/test-cases.js';
13
- const server = new McpServer({
14
- name: 'sentinel',
15
- version: '1.0.0',
15
+ serveStdio(() => {
16
+ const server = new McpServer({ name: 'sentinel', version: metadata.version });
17
+ registerTestCaseTools(server);
18
+ registerFunctionalityTools(server);
19
+ return server;
16
20
  });
17
- registerTestCaseTools(server);
18
- const transport = new StdioServerTransport();
19
- await server.connect(transport);
@@ -0,0 +1,2 @@
1
+ import type { McpServer } from '@modelcontextprotocol/server';
2
+ export declare function registerFunctionalityTools(server: McpServer): void;
@@ -0,0 +1,60 @@
1
+ import * as api from '../lib/api-client.js';
2
+ import { toolRequest } from '../lib/tool-result.js';
3
+ import { createFunctionalitySchema, deleteFunctionalitySchema, getFunctionalitySchema, listFunctionalitiesSchema, moveFunctionalityCasesSchema, moveFunctionalitySchema, updateFunctionalitySchema, } from './functionality-schemas.js';
4
+ export function registerFunctionalityTools(server) {
5
+ registerReads(server);
6
+ registerCreate(server);
7
+ registerUpdate(server);
8
+ registerMove(server);
9
+ registerDelete(server);
10
+ registerCaseTransfer(server);
11
+ }
12
+ function registerReads(server) {
13
+ server.registerTool('sentinel_list_functionalities', {
14
+ description: 'List project functionalities with parent_id and pagination. Follow pagination to see the complete two-level hierarchy.',
15
+ inputSchema: listFunctionalitiesSchema,
16
+ annotations: { readOnlyHint: true },
17
+ }, ({ project_id, page = 1, page_size = 20 }) => toolRequest(() => api.get('/api/mcp/functionalities', {
18
+ project_id,
19
+ page: page?.toString(),
20
+ page_size: page_size?.toString(),
21
+ })));
22
+ server.registerTool('sentinel_get_functionality', {
23
+ description: 'Get functionality details, including its project and parent. Read before editing or deleting.',
24
+ inputSchema: getFunctionalitySchema,
25
+ annotations: { readOnlyHint: true },
26
+ }, ({ id }) => toolRequest(() => api.get(`/api/mcp/functionalities/${id}`)));
27
+ }
28
+ function registerCreate(server) {
29
+ server.registerTool('sentinel_create_functionality', {
30
+ description: 'Create a root or child functionality. parent_id must reference a root in the same project; omit it or use null for a root. Maximum depth is two levels.',
31
+ inputSchema: createFunctionalitySchema,
32
+ }, (params) => toolRequest(() => api.post('/api/mcp/functionalities', params)));
33
+ }
34
+ function registerUpdate(server) {
35
+ server.registerTool('sentinel_update_functionality', {
36
+ description: 'Partially edit name, description, color, status or parent_id. Omitted fields are preserved; null clears description/color or promotes to root. Cannot change project.',
37
+ inputSchema: updateFunctionalitySchema,
38
+ }, ({ id, ...changes }) => toolRequest(() => api.patch(`/api/mcp/functionalities/${id}`, changes)));
39
+ }
40
+ function registerMove(server) {
41
+ server.registerTool('sentinel_move_functionality', {
42
+ description: 'Move a functionality under another root in the same project, or promote it with parent_id:null. A functionality with children cannot become a child. Test cases stay attached.',
43
+ inputSchema: moveFunctionalitySchema,
44
+ }, ({ id, parent_id }) => toolRequest(() => api.patch(`/api/mcp/functionalities/${id}`, { parent_id })));
45
+ }
46
+ function registerDelete(server) {
47
+ server.registerTool('sentinel_delete_functionality', {
48
+ description: 'Delete a functionality after confirming the target. Preserve all test cases: unlink them by default or transfer to target_id, an active functionality in the same project. Direct children become roots.',
49
+ inputSchema: deleteFunctionalitySchema,
50
+ annotations: { destructiveHint: true },
51
+ }, ({ id, target_id }) => toolRequest(() => api.del(`/api/mcp/functionalities/${id}${target_id ? `?target_id=${encodeURIComponent(target_id)}` : ''}`)));
52
+ }
53
+ function registerCaseTransfer(server) {
54
+ server.registerTool('sentinel_move_functionality_test_cases', {
55
+ description: 'Atomically move 1–100 selected test cases to an active functionality in the same project. Rejects mixed projects, unauthorized cases and duplicate IDs; requires features.edit and test_cases.edit.',
56
+ inputSchema: moveFunctionalityCasesSchema,
57
+ }, ({ target_functionality_id, test_case_ids }) => toolRequest(() => api.post(`/api/mcp/functionalities/${target_functionality_id}/test-cases/move`, {
58
+ test_case_ids,
59
+ })));
60
+ }
@@ -0,0 +1,43 @@
1
+ import { z } from 'zod';
2
+ export declare const listFunctionalitiesSchema: z.ZodObject<{
3
+ project_id: z.ZodString;
4
+ page: z.ZodDefault<z.ZodNumber>;
5
+ page_size: z.ZodDefault<z.ZodNumber>;
6
+ }, z.core.$strict>;
7
+ export declare const createFunctionalitySchema: z.ZodObject<{
8
+ project_id: z.ZodString;
9
+ status: z.ZodDefault<z.ZodEnum<{
10
+ Ativa: "Ativa";
11
+ Inativa: "Inativa";
12
+ }>>;
13
+ name: z.ZodString;
14
+ description: z.ZodOptional<z.ZodString>;
15
+ color: z.ZodOptional<z.ZodNullable<z.ZodString>>;
16
+ parent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
17
+ }, z.core.$strict>;
18
+ export declare const getFunctionalitySchema: z.ZodObject<{
19
+ id: z.ZodString;
20
+ }, z.core.$strict>;
21
+ export declare const updateFunctionalitySchema: z.ZodObject<{
22
+ description: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
23
+ name: z.ZodOptional<z.ZodString>;
24
+ color: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
25
+ status: z.ZodOptional<z.ZodEnum<{
26
+ Ativa: "Ativa";
27
+ Inativa: "Inativa";
28
+ }>>;
29
+ parent_id: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
30
+ id: z.ZodString;
31
+ }, z.core.$strict>;
32
+ export declare const moveFunctionalitySchema: z.ZodObject<{
33
+ id: z.ZodString;
34
+ parent_id: z.ZodNullable<z.ZodString>;
35
+ }, z.core.$strict>;
36
+ export declare const deleteFunctionalitySchema: z.ZodObject<{
37
+ id: z.ZodString;
38
+ target_id: z.ZodOptional<z.ZodString>;
39
+ }, z.core.$strict>;
40
+ export declare const moveFunctionalityCasesSchema: z.ZodObject<{
41
+ target_functionality_id: z.ZodString;
42
+ test_case_ids: z.ZodArray<z.ZodString>;
43
+ }, z.core.$strict>;
@@ -0,0 +1,77 @@
1
+ import { z } from 'zod';
2
+ const fields = {
3
+ name: z.string().min(2).max(200).describe('Functionality name'),
4
+ description: z.string().optional().describe('Functionality description'),
5
+ color: z
6
+ .string()
7
+ .regex(/^#[0-9A-Fa-f]{6}$/)
8
+ .nullable()
9
+ .optional()
10
+ .describe('Hex color or null'),
11
+ status: z.enum(['Ativa', 'Inativa']).describe('Functionality status'),
12
+ parent_id: z.string().uuid().nullable().optional().describe('Root parent UUID; null for a root'),
13
+ };
14
+ export const listFunctionalitiesSchema = z
15
+ .object({
16
+ project_id: z.string().uuid().describe('Project UUID'),
17
+ page: z.number().int().min(1).max(1_000_000).default(1).describe('Page number (default: 1)'),
18
+ page_size: z
19
+ .number()
20
+ .int()
21
+ .min(1)
22
+ .max(100)
23
+ .default(20)
24
+ .describe('Page size (default: 20, max: 100)'),
25
+ })
26
+ .strict();
27
+ export const createFunctionalitySchema = z
28
+ .object({
29
+ ...fields,
30
+ project_id: z.string().uuid().describe('Project UUID'),
31
+ status: fields.status.default('Ativa'),
32
+ })
33
+ .strict();
34
+ export const getFunctionalitySchema = z.object({ id: z.string().uuid() }).strict();
35
+ export const updateFunctionalitySchema = z
36
+ .object({
37
+ ...fields,
38
+ description: z.string().nullable().optional().describe('Description; null clears it'),
39
+ })
40
+ .partial()
41
+ .extend({ id: z.string().uuid() })
42
+ .strict()
43
+ .refine(({ id, ...changes }) => Object.keys(changes).length > 0, 'Supply at least one changed field')
44
+ .refine(({ id, parent_id }) => id !== parent_id, 'A functionality cannot be its own parent');
45
+ export const moveFunctionalitySchema = z
46
+ .object({
47
+ id: z.string().uuid().describe('Functionality to move'),
48
+ parent_id: z
49
+ .string()
50
+ .uuid()
51
+ .nullable()
52
+ .describe('New root parent UUID, or null to promote to root'),
53
+ })
54
+ .strict()
55
+ .refine(({ id, parent_id }) => id !== parent_id, 'A functionality cannot be its own parent');
56
+ export const deleteFunctionalitySchema = z
57
+ .object({
58
+ id: z.string().uuid().describe('Functionality to delete'),
59
+ target_id: z
60
+ .string()
61
+ .uuid()
62
+ .optional()
63
+ .describe('Optional active destination for its cases; otherwise unlink'),
64
+ })
65
+ .strict()
66
+ .refine(({ id, target_id }) => id !== target_id, 'Destination must differ from source');
67
+ export const moveFunctionalityCasesSchema = z
68
+ .object({
69
+ target_functionality_id: z.string().uuid().describe('Active destination functionality UUID'),
70
+ test_case_ids: z
71
+ .array(z.string().uuid())
72
+ .min(1)
73
+ .max(100)
74
+ .refine((ids) => new Set(ids).size === ids.length, 'Duplicate case IDs are not allowed')
75
+ .describe('1–100 unique case UUIDs in the same project as the destination'),
76
+ })
77
+ .strict();
@@ -3,5 +3,5 @@
3
3
  *
4
4
  * Tool definitions for managing Sentinel test cases via MCP.
5
5
  */
6
- import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
6
+ import type { McpServer } from '@modelcontextprotocol/server';
7
7
  export declare function registerTestCaseTools(server: McpServer): void;
@@ -5,11 +5,15 @@
5
5
  */
6
6
  import { z } from 'zod';
7
7
  import * as api from '../lib/api-client.js';
8
+ import { errorResult } from '../lib/tool-result.js';
8
9
  export function registerTestCaseTools(server) {
9
10
  // =========================================================================
10
11
  // sentinel_list_projects
11
12
  // =========================================================================
12
- server.tool('sentinel_list_projects', 'List all projects in the Sentinel workspace. Use this first to get project IDs.', {}, async () => {
13
+ server.registerTool('sentinel_list_projects', {
14
+ description: 'List all projects in the Sentinel workspace. Use this first to get project IDs.',
15
+ inputSchema: z.object({}),
16
+ }, async () => {
13
17
  try {
14
18
  const result = await api.get('/api/mcp/projects');
15
19
  return { content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }] };
@@ -19,76 +23,41 @@ export function registerTestCaseTools(server) {
19
23
  }
20
24
  });
21
25
  // =========================================================================
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
26
  // sentinel_list_test_cases
64
27
  // =========================================================================
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)'),
28
+ server.registerTool('sentinel_list_test_cases', {
29
+ description: '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).',
30
+ inputSchema: z.object({
31
+ project_id: z.string().uuid().optional().describe('Filter by project UUID'),
32
+ functionality_id: z.string().uuid().optional().describe('Filter by functionality UUID'),
33
+ search: z.string().optional().describe('Search in title, CT_ID, gherkin, and notes'),
34
+ priority: z.enum(['Baixa', 'Média', 'Alta']).optional().describe('Filter by priority'),
35
+ test_status: z
36
+ .enum(['Automatizado', 'Manual'])
37
+ .optional()
38
+ .describe('Filter by test status'),
39
+ scenario_status: z
40
+ .enum(['Ativo', 'Inativo', 'Descontinuado'])
41
+ .optional()
42
+ .describe('Filter by scenario status'),
43
+ scenario_type: z
44
+ .enum(['Positivo', 'Negativo'])
45
+ .optional()
46
+ .describe('Filter by scenario type'),
47
+ sort_by: z
48
+ .enum(['created_at', 'updated_at', 'title', 'priority', 'ct_id'])
49
+ .optional()
50
+ .describe('Sort field (default: created_at)'),
51
+ sort_order: z.enum(['asc', 'desc']).optional().describe('Sort direction (default: asc)'),
52
+ page: z.number().int().min(1).optional().describe('Page number (default: 1)'),
53
+ page_size: z
54
+ .number()
55
+ .int()
56
+ .min(1)
57
+ .max(100)
58
+ .optional()
59
+ .describe('Items per page (default: 20, max: 100)'),
60
+ }),
92
61
  }, async (params) => {
93
62
  try {
94
63
  const queryParams = {};
@@ -124,7 +93,10 @@ export function registerTestCaseTools(server) {
124
93
  // =========================================================================
125
94
  // sentinel_get_test_case
126
95
  // =========================================================================
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 }) => {
96
+ server.registerTool('sentinel_get_test_case', {
97
+ description: 'Get detailed information about a specific test case by ID.',
98
+ inputSchema: z.object({ id: z.string().uuid().describe('Test case UUID') }),
99
+ }, async ({ id }) => {
128
100
  try {
129
101
  const result = await api.get(`/api/mcp/test-cases/${id}`);
130
102
  return { content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }] };
@@ -136,25 +108,28 @@ export function registerTestCaseTools(server) {
136
108
  // =========================================================================
137
109
  // sentinel_create_test_case
138
110
  // =========================================================================
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'),
111
+ server.registerTool('sentinel_create_test_case', {
112
+ description: 'Create a new test case in Sentinel. Requires project_id (use sentinel_list_projects first). Use sentinel_list_functionalities to get functionality_id.',
113
+ inputSchema: z.object({
114
+ project_id: z.string().uuid().describe('Project UUID (required)'),
115
+ functionality_id: z.string().uuid().optional().describe('Functionality UUID (optional)'),
116
+ title: z.string().min(5).max(500).describe('Test case title (min 5 chars)'),
117
+ scenario_type: z.enum(['Positivo', 'Negativo']).describe('Scenario type'),
118
+ gherkin: z.string().min(1).describe('Gherkin/BDD scenario text'),
119
+ priority: z.enum(['Baixa', 'Média', 'Alta']).describe('Priority level'),
120
+ test_status: z.enum(['Automatizado', 'Manual']).describe('Test status'),
121
+ should_automate: z.boolean().describe('Whether this test should be automated'),
122
+ platforms: z
123
+ .array(z.enum(['Desktop', 'Mobile', 'API']))
124
+ .min(1)
125
+ .describe('Target platforms (at least one)'),
126
+ scenario_status: z
127
+ .enum(['Ativo', 'Inativo', 'Descontinuado'])
128
+ .default('Ativo')
129
+ .describe('Scenario status (default: Ativo)'),
130
+ notes: z.string().optional().describe('Additional notes'),
131
+ assigned_to: z.string().uuid().optional().describe('User UUID to assign the test case to'),
132
+ }),
158
133
  }, async (params) => {
159
134
  try {
160
135
  const result = await api.post('/api/mcp/test-cases', params);
@@ -174,37 +149,40 @@ export function registerTestCaseTools(server) {
174
149
  // =========================================================================
175
150
  // sentinel_update_test_case
176
151
  // =========================================================================
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)'),
152
+ server.registerTool('sentinel_update_test_case', {
153
+ description: 'Update an existing test case. Supports partial updates — only provided fields will be changed. Use sentinel_get_test_case first to see current values.',
154
+ inputSchema: z.object({
155
+ id: z.string().uuid().describe('Test case UUID to update'),
156
+ project_id: z.string().uuid().optional().describe('Project UUID'),
157
+ functionality_id: z
158
+ .string()
159
+ .uuid()
160
+ .optional()
161
+ .nullable()
162
+ .describe('Functionality UUID (null to remove)'),
163
+ title: z.string().min(5).max(500).optional().describe('Test case title'),
164
+ scenario_type: z.enum(['Positivo', 'Negativo']).optional().describe('Scenario type'),
165
+ gherkin: z.string().min(1).optional().describe('Gherkin/BDD scenario text'),
166
+ priority: z.enum(['Baixa', 'Média', 'Alta']).optional().describe('Priority level'),
167
+ test_status: z.enum(['Automatizado', 'Manual']).optional().describe('Test status'),
168
+ should_automate: z.boolean().optional().describe('Whether this test should be automated'),
169
+ platforms: z
170
+ .array(z.enum(['Desktop', 'Mobile', 'API']))
171
+ .min(1)
172
+ .optional()
173
+ .describe('Target platforms'),
174
+ scenario_status: z
175
+ .enum(['Ativo', 'Inativo', 'Descontinuado'])
176
+ .optional()
177
+ .describe('Scenario status'),
178
+ notes: z.string().optional().nullable().describe('Additional notes (null to remove)'),
179
+ assigned_to: z
180
+ .string()
181
+ .uuid()
182
+ .optional()
183
+ .nullable()
184
+ .describe('User UUID to assign (null to unassign)'),
185
+ }),
208
186
  }, async ({ id, ...body }) => {
209
187
  try {
210
188
  const result = await api.patch(`/api/mcp/test-cases/${id}`, body);
@@ -224,7 +202,10 @@ export function registerTestCaseTools(server) {
224
202
  // =========================================================================
225
203
  // sentinel_delete_test_case
226
204
  // =========================================================================
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 }) => {
205
+ server.registerTool('sentinel_delete_test_case', {
206
+ description: 'Delete a test case by ID. This action is irreversible. Requires test_cases.delete permission.',
207
+ inputSchema: z.object({ id: z.string().uuid().describe('Test case UUID to delete') }),
208
+ }, async ({ id }) => {
228
209
  try {
229
210
  const result = await api.del(`/api/mcp/test-cases/${id}`);
230
211
  return {
@@ -241,11 +222,3 @@ export function registerTestCaseTools(server) {
241
222
  }
242
223
  });
243
224
  }
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 CHANGED
@@ -1,29 +1,47 @@
1
1
  {
2
2
  "name": "mcp-sentinel-qa",
3
- "version": "1.0.0",
4
- "description": "MCP server for Sentinel QA — manage test cases from any AI assistant",
3
+ "version": "2.0.1",
4
+ "description": "MCP server for Sentinel QA — manage functionalities and test cases from any AI assistant",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
+ "author": "João Vitor Matos",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/JVMatos/sentinel.git",
11
+ "directory": "mcp"
12
+ },
13
+ "bugs": {
14
+ "url": "https://github.com/JVMatos/sentinel/issues"
15
+ },
7
16
  "bin": {
8
17
  "mcp-sentinel-qa": "dist/server.js"
9
18
  },
10
- "files": ["dist"],
19
+ "files": ["dist", "CHANGELOG.md"],
11
20
  "scripts": {
12
21
  "build": "tsc",
22
+ "type-check": "tsc --noEmit",
23
+ "test": "node --test tests/*.test.mjs && MCP_TEST_CLIENT=modern node --test tests/*.test.mjs",
24
+ "test:package": "node scripts/verify-package.mjs",
25
+ "check": "pnpm --ignore-workspace run type-check && pnpm --ignore-workspace run build && pnpm --ignore-workspace run test",
13
26
  "dev": "tsx server.ts",
14
- "prepublishOnly": "tsc"
27
+ "prepack": "pnpm --ignore-workspace run check",
28
+ "prepublishOnly": "pnpm --ignore-workspace audit --prod"
15
29
  },
16
- "keywords": ["mcp", "sentinel", "qa", "testing", "test-cases"],
30
+ "keywords": ["mcp", "sentinel", "qa", "testing", "functionalities", "test-cases"],
17
31
  "homepage": "https://sentinel-qa.vercel.app",
18
32
  "dependencies": {
19
- "@modelcontextprotocol/sdk": "^1.12.1",
20
- "zod": "^3.24.4"
33
+ "@modelcontextprotocol/server": "^2.4.0",
34
+ "zod": "^4.6.7"
21
35
  },
22
36
  "devDependencies": {
23
- "typescript": "^5.9.0",
24
- "tsx": "^4.19.4"
37
+ "@modelcontextprotocol/client": "^2.4.0",
38
+ "@modelcontextprotocol/sdk": "^1.32.2",
39
+ "@types/node": "^22.20.5",
40
+ "tsx": "^4.23.15",
41
+ "typescript": "~5.9.3"
25
42
  },
26
43
  "engines": {
27
- "node": ">=18"
28
- }
44
+ "node": ">=22"
45
+ },
46
+ "packageManager": "pnpm@11.20.0"
29
47
  }