youtrack-kb-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rkorablin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ONBOARDING_PROMPT.md

@@ -0,0 +1,9 @@
+# Onboarding: youtrack-kb-mcp
+
+This repo is a single-purpose MCP server for YouTrack Knowledge Base (Articles). There is no UI or long-running service; the server runs over stdio and is started by the MCP host (e.g. Cursor).
+
+- **Setup:** clone, `npm install`, set `YOUTRACK_URL` and `YOUTRACK_TOKEN`, then add the server to your MCP config (see README).
+- **Code:** `server.mjs` is the only application file; it uses `@modelcontextprotocol/sdk` for stdio transport and tool definitions.
+- **No hardcoded URLs or tokens** — all configuration is via environment variables so the same code can be used in any environment or published as-is.
+
+**Продолжение в новой сессии (экосистема ~/ai/):** проект входит в воркспейс **~/ai/general/ai.code-workspace**. Чтобы при работе в этом репо подхватывались общие MCP и правила Cursor из **general**, создай локально (не коммитить): `.cursor/mcp.json` → симлинк на `../../general/.cursor/mcp.json`, в `.cursor/rules/` — симлинки на файлы из `../../general/.cursor/rules/*.mdc`. Подробно: **~/ai/general/RULE_PROJECTS.md**. Статус проекта в экосистеме: **~/ai/general/PROJECTS_STATUS.md**.

package/README.md

@@ -0,0 +1,79 @@
+# youtrack-kb-mcp
+
+MCP (Model Context Protocol) server for **YouTrack Knowledge Base** (Articles). Lets AI assistants list, read, create, and update KB articles via stdio transport.
+
+Works with any YouTrack instance that exposes the [Articles API](https://www.jetbrains.com/help/youtrack/server/api/articles.html) (YouTrack 2024.2+).
+
+**Repositories:** [GitHub](https://github.com/rkorablin/youtrack-kb-mcp) · [GitLab](https://gitlab.greenworm.ru/ai/youtrack-kb-mcp)
+
+## Requirements
+
+- Node.js 18+
+- YouTrack base URL and a [permanent token](https://www.jetbrains.com/help/youtrack/server/manage-personal-access-tokens.html) with permission to manage articles
+
+## Install
+
+**From npm:**
+
+```bash
+npm install youtrack-kb-mcp
+```
+
+**From source (GitHub or GitLab):**
+
+```bash
+git clone https://github.com/rkorablin/youtrack-kb-mcp.git youtrack-kb-mcp
+cd youtrack-kb-mcp
+npm install
+```
+
+## Configuration
+
+Set environment variables:
+
+| Variable         | Required | Description                                      |
+|------------------|----------|--------------------------------------------------|
+| `YOUTRACK_URL`   | Yes      | YouTrack base URL (e.g. `https://youtrack.example.com`) |
+| `YOUTRACK_TOKEN` | Yes      | Permanent token (Bearer)                         |
+
+No default URLs or tokens; safe to publish and use in any environment.
+
+## Usage
+
+### Standalone (stdio)
+
+```bash
+export YOUTRACK_URL="https://youtrack.example.com"
+export YOUTRACK_TOKEN="perm-..."
+node server.mjs
+```
+
+### Cursor / MCP host
+
+Add to your MCP config (e.g. `.cursor/mcp.json` under `mcpServers`):
+
+```json
+"youtrack-kb": {
+  "command": "node",
+  "args": ["/path/to/youtrack-kb-mcp/server.mjs"],
+  "env": {
+    "YOUTRACK_URL": "https://youtrack.example.com",
+    "YOUTRACK_TOKEN": "YOUR_TOKEN"
+  }
+}
+```
+
+Replace `/path/to/youtrack-kb-mcp` with the directory where you cloned this repo, and set your YouTrack URL and token. Do not commit tokens; use a local config or env file excluded from version control.
+
+## Tools
+
+| Tool                       | Description                    |
+|----------------------------|--------------------------------|
+| `youtrack_kb_list_articles` | List articles (optional project, pagination) |
+| `youtrack_kb_get_article`    | Get one article by id         |
+| `youtrack_kb_create_article` | Create article (summary, content, project) |
+| `youtrack_kb_update_article`| Update article summary and/or content |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "youtrack-kb-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for YouTrack Knowledge Base (Articles API)",
+  "type": "module",
+  "main": "server.mjs",
+  "bin": {
+    "youtrack-kb-mcp": "server.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rkorablin/youtrack-kb-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "youtrack",
+    "knowledge-base",
+    "articles"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/server.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * MCP server for YouTrack Knowledge Base (Articles).
+ * Requires env: YOUTRACK_URL (base URL, e.g. https://youtrack.example.com), YOUTRACK_TOKEN (Bearer token).
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const baseUrl = (process.env.YOUTRACK_URL || '').replace(/\/$/, '');
+const token = process.env.YOUTRACK_TOKEN;
+const api = baseUrl ? `${baseUrl}/api` : '';
+
+function authHeaders() {
+  if (!baseUrl) throw new Error('YOUTRACK_URL is required');
+  if (!token) throw new Error('YOUTRACK_TOKEN is required');
+  return { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
+}
+
+async function ytFetch(path, opts = {}) {
+  const res = await fetch(`${api}${path}`, { ...opts, headers: { ...authHeaders(), ...opts.headers } });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}: ${text.slice(0, 400)}`);
+  return text ? JSON.parse(text) : null;
+}
+
+const server = new Server(
+  { name: 'youtrack-kb-mcp', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'youtrack_kb_list_articles',
+      description: 'List YouTrack Knowledge Base articles. Optional filter by project (projectShortName), pagination: top and skip.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          projectShortName: { type: 'string', description: 'Project key, e.g. GEN' },
+          top: { type: 'number', description: 'Max articles (default 50)', default: 50 },
+          skip: { type: 'number', description: 'Skip N articles for pagination (default 0)', default: 0 }
+        }
+      }
+    },
+    {
+      name: 'youtrack_kb_get_article',
+      description: 'Get a single article by id (e.g. GEN-A-1 or database id).',
+      inputSchema: {
+        type: 'object',
+        properties: { articleId: { type: 'string', description: 'Article id (idReadable or id)' } },
+        required: ['articleId']
+      }
+    },
+    {
+      name: 'youtrack_kb_create_article',
+      description: 'Create an article in YouTrack Knowledge Base in the given project.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          projectShortName: { type: 'string', description: 'Project key', default: 'GEN' },
+          summary: { type: 'string', description: 'Article title' },
+          content: { type: 'string', description: 'Article body (Markdown)' }
+        },
+        required: ['summary']
+      }
+    },
+    {
+      name: 'youtrack_kb_update_article',
+      description: 'Update an article (summary and/or content). At least one of summary or content must be provided.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          articleId: { type: 'string', description: 'Article id' },
+          summary: { type: 'string', description: 'New title' },
+          content: { type: 'string', description: 'New body (Markdown)' }
+        },
+        required: ['articleId']
+      }
+    }
+  ]
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  const a = args || {};
+
+  try {
+    if (name === 'youtrack_kb_list_articles') {
+      const project = a.projectShortName;
+      const top = Math.max(1, Math.min(100, Number(a.top) || 50));
+      const skip = Math.max(0, Number(a.skip) || 0);
+      const q = `fields=id,idReadable,summary,project(shortName),updated&$top=${top}&$skip=${skip}`;
+      const path = project
+        ? `/admin/projects/${encodeURIComponent(project)}/articles?${q}`
+        : `/articles?${q}`;
+      const data = await ytFetch(path);
+      return { content: [{ type: 'text', text: JSON.stringify(Array.isArray(data) ? data : [], null, 2) }] };
+    }
+
+    if (name === 'youtrack_kb_get_article') {
+      const id = a.articleId;
+      if (!id) throw new Error('articleId is required');
+      const data = await ytFetch(`/articles/${encodeURIComponent(id)}?fields=id,idReadable,summary,content,project(shortName),updated`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    }
+
+    if (name === 'youtrack_kb_create_article') {
+      const projectShortName = a.projectShortName || 'GEN';
+      const summary = a.summary || '';
+      const content = a.content || '';
+      const body = { project: { shortName: projectShortName }, summary, content };
+      const data = await ytFetch('/articles?fields=id,idReadable,summary', { method: 'POST', body: JSON.stringify(body) });
+      const id = data?.idReadable ?? data?.id ?? '?';
+      return { content: [{ type: 'text', text: `Created article: ${id} — ${data?.summary ?? summary}` }] };
+    }
+
+    if (name === 'youtrack_kb_update_article') {
+      const articleId = a.articleId;
+      if (!articleId) throw new Error('articleId is required');
+      const body = {};
+      if (a.summary != null) body.summary = a.summary;
+      if (a.content != null) body.content = a.content;
+      if (Object.keys(body).length === 0) throw new Error('Provide at least one of summary or content');
+      await ytFetch(`/articles/${encodeURIComponent(articleId)}`, { method: 'POST', body: JSON.stringify(body) });
+      return { content: [{ type: 'text', text: `Article ${articleId} updated` }] };
+    }
+
+    throw new Error(`Unknown tool: ${name}`);
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);