@daghis/teamcity-mcp 0.1.2 → 0.2.1

package/scripts/generate-third-party-notices.cjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/*
+ Generates THIRD_PARTY_NOTICES.md from installed packages.
+ Reads direct deps and devDeps from package.json and extracts
+ name, version, and license from node_modules/<pkg>/package.json.
+*/
+const fs = require('fs');
+const path = require('path');
+
+function readJSON(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function pkgInfo(name) {
+  try {
+    const p = path.join('node_modules', ...name.split('/'));
+    const data = readJSON(path.join(p, 'package.json'));
+    // Normalize license string
+    let license = 'UNKNOWN';
+    if (typeof data.license === 'string') license = data.license;
+    else if (data.license && typeof data.license.type === 'string') license = data.license.type;
+    else if (Array.isArray(data.licenses) && data.licenses.length && data.licenses[0].type)
+      license = data.licenses[0].type;
+    return { name, version: data.version || 'UNKNOWN', license };
+  } catch {
+    return { name, version: 'UNKNOWN', license: 'UNKNOWN' };
+  }
+}
+
+function generate() {
+  const pkg = readJSON(path.join(process.cwd(), 'package.json'));
+  const prod = Object.keys(pkg.dependencies || {}).sort().map(pkgInfo);
+  const dev = Object.keys(pkg.devDependencies || {}).sort().map(pkgInfo);
+
+  const lines = [];
+  lines.push('# Third-Party Notices');
+  lines.push('');
+  lines.push(
+    'This project includes third-party software. The following lists the direct dependencies and their licenses as resolved in this workspace. For full license texts, see each package’s own repository or the copies included in `node_modules/<package>/LICENSE` when present.'
+  );
+  lines.push('');
+  lines.push(
+    'If a dependency is not currently installed in `node_modules`, its version or license may be shown as UNKNOWN below; consult the package’s metadata for definitive terms.'
+  );
+  lines.push('');
+  const now = new Date();
+  const isoDate = now.toISOString().slice(0, 10);
+  lines.push(`Last updated: ${isoDate}`);
+  lines.push('');
+
+  lines.push('## Production Dependencies');
+  lines.push('');
+  for (const i of prod) lines.push(`- ${i.name} ${i.version} — ${i.license}`);
+  lines.push('');
+
+  lines.push('## Development Dependencies');
+  lines.push('');
+  for (const i of dev) lines.push(`- ${i.name} ${i.version} — ${i.license}`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push(
+    'Note: This document is provided for convenience and does not modify any license terms. All third-party packages remain the property of their respective copyright holders and are licensed under their own terms.'
+  );
+  lines.push('');
+
+  fs.writeFileSync('THIRD_PARTY_NOTICES.md', lines.join('\n'));
+}
+
+generate();
+

package/src/middleware/global-error-handler.ts

@@ -4,6 +4,7 @@
  */
 import { AxiosError } from 'axios';
 
+import { TeamCityAPIError } from '@/teamcity/errors';
 import { ErrorContext, errorLogger } from '@/utils/error-logger';
 
 import {
@@ -98,6 +99,16 @@ export class GlobalErrorHandler {
    * Transform raw errors into structured MCP errors
    */
   private transformError(error: unknown, context: ErrorContext): Error {
+    // Errors already normalized by our TeamCity client
+    if (error instanceof TeamCityAPIError) {
+      return new MCPTeamCityError(
+        this.sanitizeErrorMessage(error.message),
+        error.statusCode ?? 500,
+        error.code,
+        context.requestId
+      );
+    }
+
     // Already an MCP error
     if (error instanceof MCPToolError) {
       // Still sanitize the message if needed

package/src/teamcity/auth.ts

@@ -7,15 +7,16 @@ import type {
   AxiosResponse,
   InternalAxiosRequestConfig,
 } from 'axios';
-import { v4 as uuidv4 } from 'uuid';
+import { randomUUID } from 'crypto';
 
+import { TeamCityAPIError } from '@/teamcity/errors';
 import { info, error as logError } from '@/utils/logger';
 
 /**
  * Generate a unique request ID for tracing
  */
 export function generateRequestId(): string {
-  return uuidv4();
+  return randomUUID();
 }
 
 /**
@@ -126,7 +127,10 @@ export function logResponse(response: AxiosResponse): AxiosResponse {
  * Log error with request ID and transform
  */
 export function logAndTransformError(error: AxiosError): Promise<never> {
-  const teamcityError = extractErrorDetails(error);
+  // Build a rich TeamCityAPIError instance so downstream handlers
+  // see an Error subclass (not a plain object)
+  const requestId = (error.config as AxiosRequestConfig & { requestId?: string })?.requestId;
+  const tcError = TeamCityAPIError.fromAxiosError(error, requestId);
   const meta = (error.config as unknown as { _tcMeta?: { start: number } })?._tcMeta;
   const duration = meta?.start ? Date.now() - meta.start : undefined;
 
@@ -148,15 +152,15 @@ export function logAndTransformError(error: AxiosError): Promise<never> {
   };
 
   logError('TeamCity API request failed', undefined, {
-    requestId: teamcityError.requestId,
-    code: teamcityError.code,
-    message: sanitize(teamcityError.message) as string,
-    statusCode: teamcityError.statusCode,
-    details: sanitize(teamcityError.details),
+    requestId: tcError.requestId,
+    code: tcError.code,
+    message: sanitize(tcError.message) as string,
+    statusCode: tcError.statusCode,
+    details: sanitize(tcError.details),
     duration,
   });
 
-  return Promise.reject(teamcityError);
+  return Promise.reject(tcError);
 }
 
 /**

package/src/tools.ts

@@ -1014,9 +1014,16 @@ const DEV_TOOLS: ToolDefinition[] = [
     description: 'Fetch server metrics (CPU/memory/disk/load) if available',
     inputSchema: { type: 'object', properties: {} },
     handler: async (_args: unknown) => {
-      const api = TeamCityAPI.getInstance();
-      const metrics = await api.server.getAllMetrics();
-      return json(metrics.data);
+      return runTool(
+        'get_server_metrics',
+        null,
+        async () => {
+          const api = TeamCityAPI.getInstance();
+          const metrics = await api.server.getAllMetrics();
+          return json(metrics.data);
+        },
+        {}
+      );
     },
     mode: 'full',
   },
@@ -1025,9 +1032,16 @@ const DEV_TOOLS: ToolDefinition[] = [
     description: 'Get TeamCity server info (version, build number, state)',
     inputSchema: { type: 'object', properties: {} },
     handler: async (_args: unknown) => {
-      const api = TeamCityAPI.getInstance();
-      const info = await api.server.getServerInfo();
-      return json(info.data);
+      return runTool(
+        'get_server_info',
+        null,
+        async () => {
+          const api = TeamCityAPI.getInstance();
+          const info = await api.server.getServerInfo();
+          return json(info.data);
+        },
+        {}
+      );
     },
   },
   {

package/.commitlintrc.js

@@ -1,3 +0,0 @@
-module.exports = {
-  extends: ['@commitlint/config-conventional'],
-};

package/TODO.md

@@ -1,80 +0,0 @@
-# OSS Launch TODO
-
-High-level checklist to complete before publishing the repository to GitHub.
-
-## Legal & Notices
-- Create `THIRD_PARTY_NOTICES.md`:
-  - Note use of JetBrains TeamCity name/trademark; clarify no affiliation or endorsement.
-  - Mention TeamCity REST API usage and link to relevant terms.
-  - Acknowledge project crafting via Anthropic’s Claude Code and OpenAI Codex CLI.
-  - List notable third‑party deps/tools: `@modelcontextprotocol/sdk`, `axios`, `zod`, `jest`, `ts-jest`, `prettier`, `eslint`, OpenAPI generator.
-- Verify LICENSE (MIT) is correct and reflected in README.
-
-## TeamCity Self‑Integration
-- Create a TeamCity project that builds this repo (self‑hosting example):
-  - Steps: install deps, `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`.
-  - Parameterize Node version via `.nvmrc` (24.7.0) and agent requirements.
-  - Configure secure `TEAMCITY_URL`/`TEAMCITY_TOKEN` (dev‑mode, read‑only) as server/agent parameters.
-  - Add triggers on `main` and PR branches; publish build artifacts (e.g., coverage report) for docs.
-  - Optional: nightly job to run integration smoke tests against a sandbox TeamCity instance.
-
-## GitHub Actions (CI/CD)
-- Add workflows (defer until ready to enable CI):
-  - `ci.yml`: Node 24, cache `~/.npm`, run `lint:check`, `format:check`, `typecheck`, and `test:coverage` (enforce thresholds); optionally upload coverage to a badge service.
-  - `release.yml`: On tag, build and publish to npm (if publishing), generate changelog and GitHub Release.
-  - `codeql.yml`: Code scanning (JavaScript/TypeScript).
-  - Optional: `e2e.yml` gated by secrets for TeamCity sandbox.
-- Configure required checks (branch protection) for `main` when CI is enabled.
-
-## OSS Best Practices
-- README badges: build status (GH Actions), coverage, npm version (if publishing), license, Node version, Prettier.
-- Add Node 24 badge and update README references to Node 24.
-- Governance docs:
-  - `CODE_OF_CONDUCT.md` (Contributor Covenant)
-  - `SECURITY.md` (reporting policy)
-  - Ensure `CONTRIBUTING.md` aligns with workflows and labels
-  - Issue/PR templates and labels (bug, feature, question, good‑first‑issue)
-- Release hygiene:
-  - `CHANGELOG.md` (keep a human‑readable log or use release‑please)
-  - Semantic versioning policy documented in README
-- Repository hygiene:
-  - `CODEOWNERS` for review routing
-  - Dependabot or Renovate for deps
-  - Stale bot policy (optional)
-
-## Packaging & Publishing
-- `package.json` metadata: `repository`, `homepage`, `bugs`, `license`, `engines`, `exports`/`bin` (if CLI), `files` whitelist.
-- Add `.npmignore` (or use `files` field) to exclude tests, local scripts, and docs not needed for package.
-- Verify build output under `dist/` matches exports and type definitions.
-
-## Codebase Quality (Housekeeping)
-- ESLint hygiene: keep `no-await-in-loop` disables narrowly scoped around intentional sequential logic (done in current codebase; verify on new contributions).
-- Remove remaining legacy `getTool(...)!` usages by migrating to `getRequiredTool` where applicable.
-- Centralize env var validation (zod) in `src/config` and use consistently.
-- Silence ESLint multi-project hint by using `tsconfig.lint.json` or enabling `noWarnOnMultipleProjects`.
-
-## Test Stability
-- Avoid forced Jest exits; rely on natural shutdown. Ensure timers are cleared in `tests/setup.ts` (added) and prefer fake timers in new tests.
-
-## Documentation
-- README refinements:
-  - Add badges, succinct Quick Start, and a minimal “Dev vs Full mode” table.
-  - Link to `docs/` and `THIRD_PARTY_NOTICES.md`.
-  - Add a short “Security & Privacy” note about token redaction and not committing secrets.
-- Docs site (optional): publish GitHub Pages or Docusaurus if scope grows.
-- Provide minimal examples in `examples/` to demonstrate common tool calls and MCP client integration.
-
-## Security & Compliance
-- Enable GitHub secret scanning and push protection.
-- Validate token redaction in logs; keep `.env.example` minimal and safe.
-- Add threat‑model notes (read‑only defaults in `dev` mode; `full` mode cautions).
-
-## Project Setup on GitHub
-- Initialize repo, push baseline, add branch protections, enable Discussions (optional).
-- Configure Actions permissions (workflows can create releases/tags if needed).
-- Configure CI required checks and status badges.
-
-## Nice‑to‑Haves (Post‑Launch)
-- Benchmarks and performance notes for large TeamCity instances.
-- Example TeamCity templates for self‑integration (YAML or screenshots).
-- Automated docs generation (OpenAPI → client usage snippets) if we add an API facade.