From 12950d322a680bcc6803152ed3f7568fe5b33752 Mon Sep 17 00:00:00 2001
From: "i.seliverstov"
Date: Fri, 9 Oct 2026 18:27:36 +0500
Subject: [PATCH 1/4] feat(auth): expose profile token management API
---
.../src/modules/auth/api-tokens.controller.ts | 48 +++++++
alfy-bot/src/modules/auth/auth.module.ts | 3 +-
.../modules/auth/dto/create-api-token.dto.ts | 11 ++
alfy-bot/test/api-tokens.e2e-spec.ts | 121 ++++++++++++++++++
4 files changed, 182 insertions(+), 1 deletion(-)
create mode 100644 alfy-bot/src/modules/auth/api-tokens.controller.ts
create mode 100644 alfy-bot/src/modules/auth/dto/create-api-token.dto.ts
create mode 100644 alfy-bot/test/api-tokens.e2e-spec.ts
diff --git a/alfy-bot/src/modules/auth/api-tokens.controller.ts b/alfy-bot/src/modules/auth/api-tokens.controller.ts
new file mode 100644
index 0000000..80c9398
--- /dev/null
+++ b/alfy-bot/src/modules/auth/api-tokens.controller.ts
@@ -0,0 +1,48 @@
+import {
+ BadRequestException,
+ Body,
+ Controller,
+ Delete,
+ Get,
+ Header,
+ HttpCode,
+ Param,
+ ParseIntPipe,
+ Post,
+ Request,
+ UseGuards,
+} from '@nestjs/common';
+import { ApiTokenService } from './application/api-token.service';
+import { CreateApiTokenDto } from './dto/create-api-token.dto';
+import { JwtAuthGuard } from './guards/jwt-auth.guard';
+import { JwtPayload } from './strategies/jwt.strategy';
+
+interface AuthRequest extends Request {
+ user: JwtPayload;
+}
+
+@Controller('auth/api-tokens')
+@UseGuards(JwtAuthGuard)
+export class ApiTokensController {
+ constructor(private readonly apiTokenService: ApiTokenService) {}
+
+ @Post()
+ @Header('Cache-Control', 'no-store')
+ create(@Request() req: AuthRequest, @Body() dto: CreateApiTokenDto) {
+ return this.apiTokenService.generate(req.user.sub, dto.name);
+ }
+
+ @Get()
+ @Header('Cache-Control', 'no-store')
+ list(@Request() req: AuthRequest) {
+ return this.apiTokenService.list(req.user.sub);
+ }
+
+ @Delete(':id')
+ @HttpCode(204)
+ @Header('Cache-Control', 'no-store')
+ revoke(@Request() req: AuthRequest, @Param('id', ParseIntPipe) id: number) {
+ if (id < 1) throw new BadRequestException('Invalid token ID');
+ return this.apiTokenService.revoke(id, req.user.sub);
+ }
+}
diff --git a/alfy-bot/src/modules/auth/auth.module.ts b/alfy-bot/src/modules/auth/auth.module.ts
index 99ef874..5161c2e 100644
--- a/alfy-bot/src/modules/auth/auth.module.ts
+++ b/alfy-bot/src/modules/auth/auth.module.ts
@@ -4,6 +4,7 @@ import { PassportModule } from '@nestjs/passport';
import { TypeOrmModule } from '@nestjs/typeorm';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { AuthController } from './auth.controller';
+import { ApiTokensController } from './api-tokens.controller';
import { AuthService } from './auth.service';
import { JwtStrategy } from './strategies/jwt.strategy';
import { JwtAuthGuard } from './guards/jwt-auth.guard';
@@ -36,7 +37,7 @@ import { EmailService } from '../email/email.service';
UserModule,
EmailModule,
],
- controllers: [AuthController],
+ controllers: [AuthController, ApiTokensController],
providers: [
AuthService,
JwtStrategy,
diff --git a/alfy-bot/src/modules/auth/dto/create-api-token.dto.ts b/alfy-bot/src/modules/auth/dto/create-api-token.dto.ts
new file mode 100644
index 0000000..5acb56c
--- /dev/null
+++ b/alfy-bot/src/modules/auth/dto/create-api-token.dto.ts
@@ -0,0 +1,11 @@
+import { Transform } from 'class-transformer';
+import { IsString, Length } from 'class-validator';
+
+export class CreateApiTokenDto {
+ @Transform(({ value }: { value: unknown }) =>
+ typeof value === 'string' ? value.trim() : value,
+ )
+ @IsString()
+ @Length(1, 100)
+ name: string;
+}
diff --git a/alfy-bot/test/api-tokens.e2e-spec.ts b/alfy-bot/test/api-tokens.e2e-spec.ts
new file mode 100644
index 0000000..c49b7cd
--- /dev/null
+++ b/alfy-bot/test/api-tokens.e2e-spec.ts
@@ -0,0 +1,121 @@
+import request from 'supertest';
+import { INestApplication } from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import { DataSource } from 'typeorm';
+import { createTestApp } from './helpers/test-app';
+import { User } from '../src/shared/entities';
+
+describe('API tokens (e2e)', () => {
+ let app: INestApplication;
+ let token: string;
+ let otherToken: string;
+ const url = '/api/auth/api-tokens';
+ const auth = (value: string) => ({ Authorization: `Bearer ${value}` });
+
+ beforeAll(async () => {
+ const context = await createTestApp();
+ app = context.app;
+ token = context.token;
+ const other = await app
+ .get(DataSource)
+ .getRepository(User)
+ .save({ telegramId: 998, username: 'other' });
+ otherToken = app.get(JwtService).sign({ telegramId: 998, sub: other.id });
+ });
+
+ afterAll(async () => {
+ await app.close();
+ });
+
+ it('creates a token once and exposes plaintext only in the creation response', async () => {
+ const created = await request(app.getHttpServer())
+ .post(url)
+ .set(auth(token))
+ .send({ name: ' Codex ', userId: 999 })
+ .expect(201);
+ expect(created.headers['cache-control']).toBe('no-store');
+ expect(created.body).toEqual({
+ id: expect.any(Number),
+ plaintext: expect.stringMatching(/^[a-f0-9]{48}$/),
+ });
+
+ const listed = await request(app.getHttpServer())
+ .get(url)
+ .set(auth(token))
+ .expect(200);
+ expect(listed.headers['cache-control']).toBe('no-store');
+ expect(listed.body).toContainEqual({
+ id: created.body.id,
+ name: 'Codex',
+ prefix: created.body.plaintext.slice(0, 10),
+ created_at: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
+ last_used_at: null,
+ });
+ expect(JSON.stringify(listed.body)).not.toContain(created.body.plaintext);
+ });
+
+ it('lists only the owner’s tokens', async () => {
+ const own = await request(app.getHttpServer())
+ .post(url)
+ .set(auth(otherToken))
+ .send({ name: 'Other token' })
+ .expect(201);
+ const listed = await request(app.getHttpServer())
+ .get(url)
+ .set(auth(token))
+ .expect(200);
+ expect(listed.body.some((entry: { id: number }) => entry.id === own.body.id)).toBe(false);
+ });
+
+ it('rejects foreign and repeated revocation', async () => {
+ const created = await request(app.getHttpServer())
+ .post(url)
+ .set(auth(token))
+ .send({ name: 'Revoke me' })
+ .expect(201);
+ const target = `${url}/${created.body.id}`;
+ await request(app.getHttpServer()).delete(target).set(auth(otherToken)).expect(404);
+ const revoked = await request(app.getHttpServer())
+ .delete(target)
+ .set(auth(token))
+ .expect(204);
+ expect(revoked.headers['cache-control']).toBe('no-store');
+ await request(app.getHttpServer()).delete(target).set(auth(token)).expect(404);
+ });
+
+ it.each(['', ' ', 'x'.repeat(101), 123, null])('rejects invalid token name %j', async (name) => {
+ await request(app.getHttpServer())
+ .post(url)
+ .set(auth(token))
+ .send({ name })
+ .expect(400);
+ });
+
+ it.each(['abc', '0', '-1', '1.2'])('rejects invalid token id %s', async (id) => {
+ await request(app.getHttpServer())
+ .delete(`${url}/${id}`)
+ .set(auth(token))
+ .expect(400);
+ });
+
+ it('rejects missing JWT on every method', async () => {
+ await request(app.getHttpServer()).get(url).expect(401);
+ await request(app.getHttpServer()).post(url).send({ name: 'Denied' }).expect(401);
+ await request(app.getHttpServer()).delete(`${url}/1`).expect(401);
+ });
+
+ it('allows task access until revocation but never token management with an API token', async () => {
+ const created = await request(app.getHttpServer())
+ .post(url)
+ .set(auth(token))
+ .send({ name: 'Agent' })
+ .expect(201);
+ const apiToken = created.body.plaintext as string;
+ await request(app.getHttpServer()).get('/api/tasks').set(auth(apiToken)).expect(200);
+ await request(app.getHttpServer()).get(url).set(auth(apiToken)).expect(401);
+ await request(app.getHttpServer()).post(url).set(auth(apiToken)).send({ name: 'Denied' }).expect(401);
+ await request(app.getHttpServer()).delete(`${url}/${created.body.id}`).set(auth(apiToken)).expect(401);
+ await request(app.getHttpServer()).delete(`${url}/${created.body.id}`).set(auth(token)).expect(204);
+ await request(app.getHttpServer()).get('/api/tasks').set(auth(apiToken)).expect(401);
+ });
+});
From 84333db91d8f868470e19a54f49accdeeb636452 Mon Sep 17 00:00:00 2001
From: "i.seliverstov"
Date: Fri, 9 Oct 2026 18:29:07 +0500
Subject: [PATCH 2/4] feat(settings): add MCP tokens and agent setup guide
---
CLAUDE.md | 4 +-
README.md | 2 +-
alfy-bot-frontend/.env.example | 1 +
.../src/features/mcp/api/tokens.ts | 18 +++
.../src/features/mcp/lib/connection-guide.ts | 28 ++++
.../src/features/mcp/model/types.ts | 12 ++
.../src/features/mcp/model/useMcpTokens.ts | 78 +++++++++
.../features/mcp/ui/McpConnectionGuide.vue | 76 +++++++++
.../src/features/mcp/ui/McpSettings.vue | 153 ++++++++++++++++++
alfy-bot-frontend/src/views/SettingsView.vue | 3 +
alfy-bot-frontend/src/vite-env.d.ts | 1 +
.../tests/features/mcp/McpSettings.spec.ts | 125 ++++++++++++++
.../features/mcp/connection-guide.spec.ts | 32 ++++
.../tests/views/SettingsView.spec.ts | 7 +
alfy-mcp/README.md | 26 ++-
15 files changed, 559 insertions(+), 7 deletions(-)
create mode 100644 alfy-bot-frontend/src/features/mcp/api/tokens.ts
create mode 100644 alfy-bot-frontend/src/features/mcp/lib/connection-guide.ts
create mode 100644 alfy-bot-frontend/src/features/mcp/model/types.ts
create mode 100644 alfy-bot-frontend/src/features/mcp/model/useMcpTokens.ts
create mode 100644 alfy-bot-frontend/src/features/mcp/ui/McpConnectionGuide.vue
create mode 100644 alfy-bot-frontend/src/features/mcp/ui/McpSettings.vue
create mode 100644 alfy-bot-frontend/tests/features/mcp/McpSettings.spec.ts
create mode 100644 alfy-bot-frontend/tests/features/mcp/connection-guide.spec.ts
diff --git a/CLAUDE.md b/CLAUDE.md
index e679650..3c80792 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,7 +8,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- `alfy-bot/` — NestJS-бэкенд (порт 3002): REST API под `/api`, Swagger на `/api/docs`, Telegram-бот (telegraf), TypeORM + SQLite (`data/database.sqlite`, `synchronize: true`), JWT + API-token auth (`JwtOrApiTokenGuard`), web-push.
- `alfy-bot-frontend/` — Vue 3 + Vite + TS + Tailwind v4 + Pinia + vue-router. PWA (`vite-plugin-pwa`, кастомный `sw.ts`). Запускается как обычный SPA и как Telegram WebApp.
-- `alfy-mcp/` — MCP-сервер (порт 3003, ESM, Node 22+): тонкая обёртка над REST `alfy-bot` для Claude Desktop/Code и удалённых MCP-клиентов. Транспорты: stdio + Streamable HTTP (endpoint `/mcp`). Auth — API-токены, выдаваемые ботом (`/mcp_token `). Не ходит в БД напрямую.
+- `alfy-mcp/` — MCP-сервер (порт 3003, ESM, Node 22+): тонкая обёртка над REST `alfy-bot` для Claude Desktop/Code и удалённых MCP-клиентов. Транспорты: stdio + Streamable HTTP (endpoint `/mcp`). Auth — API-токены, выдаваемые в настройках веб-приложения или ботом (`/mcp_token `). Не ходит в БД напрямую.
- `docker-compose.yml` + `Caddyfile` — прод: Caddy на 80/443 раздаёт `tracker.rocketup.tech`, проксирует `/api/*` на backend, `/mcp` + `/mcp/*` на alfy-mcp, остальное на frontend (nginx).
- `scripts/tunnels.sh` — Cloudflare Quick Tunnels для dev (см. README).
@@ -57,7 +57,7 @@ npm run test # vitest run
npm run lint # eslint .
```
-ESM-пакет, Node 22+. SDK — `@modelcontextprotocol/sdk` (`McpServer` + `StreamableHTTPServerTransport`). Auth — API-токены через бот (`/mcp_token `), хранятся как bcrypt-хеш + 10-char prefix-index в БД (`api_token` entity). Tools — тонкая обёртка над REST `alfy-bot` (1 HTTP-вызов на tool, кроме `get_progress` — 3 параллельных). См. `alfy-mcp/README.md` для подключения из клиентов.
+ESM-пакет, Node 22+. SDK — `@modelcontextprotocol/sdk` (`McpServer` + `StreamableHTTPServerTransport`). Auth — API-токены из настроек профиля или Telegram-команды `/mcp_token `, хранятся как bcrypt-хеш + 10-char prefix-index в БД (`api_token` entity). В настройках токен показывается только при выдаче, затем доступен только его префикс; отзыв прекращает доступ. Управление токенами через `/api/auth/api-tokens` доступно только с JWT, не с API-токеном. Для HTTP-клиентов адрес в production — `https://tracker.rocketup.tech/mcp`, локально — `http://localhost:3003/mcp`; `VITE_MCP_URL` задаёт адрес в инструкции фронта, без неё используется `/mcp` текущего origin. Tools — тонкая обёртка над REST `alfy-bot` (1 HTTP-вызов на tool, кроме `get_progress` — 3 параллельных). См. `alfy-mcp/README.md` для подключения из клиентов.
**MCP-планирование спринтов.** `tools/sprints.ts` регистрируется в общем `createServer` для обоих транспортов. Контроллеры спринтов и групп используют `JwtOrApiTokenGuard`, иначе MCP API-токен получает 401. `move_story_to_sprint` вызывает атомарный серверный перенос; не заменять его циклом обновления задач. `complete_sprint` требует явный `moveTo`, `delete_sprint` — `confirm: true`. У задач доступны `groupId`/`sprintId` и фильтр `sprint_id`; создание без `sprintId` наследует спринт истории. Контракты проверяются через реальный MCP SDK в `alfy-mcp/tests/tools/sprints.spec.ts` и HTTP-тест API-токена в `alfy-bot/test/story-sprint.e2e-spec.ts`.
diff --git a/README.md b/README.md
index 0908884..b4a9798 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
## Чем интересен проект
-- **🤖 AI-native через MCP.** Отдельный [MCP-сервер](alfy-mcp/) даёт Claude Desktop / Claude Code полный набор инструментов для управления задачами, целями и привычками. Можно сказать ассистенту «создай цель на квартал и распиши привычки» — и он сделает это через типизированные tools, а не парсинг текста. Транспорты stdio и Streamable HTTP, авторизация по API-токенам из бота.
+- **🤖 AI-native через MCP.** Отдельный [MCP-сервер](alfy-mcp/) даёт Claude Desktop / Claude Code полный набор инструментов для управления задачами, целями и привычками. Можно сказать ассистенту «создай цель на квартал и распиши привычки» — и он сделает это через типизированные tools, а не парсинг текста. Транспорты stdio и Streamable HTTP, авторизация по API-токенам из настроек профиля или бота.
- **🎯 Цели → привычки → честный self-report.** Цель раскладывается на вопросы-привычки с расписанием (ежедневно / по дням недели / с интервалом). Семь типов вопросов: текст, оценка числом, оценка смайликами, да/нет, число, затраченное время, фото. Данные опроса — основа для аналитики и коучинга, а не «галочка выполнено».
- **📱 Три поверхности, один бэкенд.** Telegram-бот (telegraf), Telegram WebApp и обычный SPA — всё работает поверх одного REST API. Веб собран как PWA (offline, web-push, установка на домашний экран).
- **🧱 Чистая архитектура.** Бэкенд — Clean Architecture по модулям (порты в `domain/`, адаптеры в `infrastructure/`, оркестрация в сервисах). Фронтенд — Feature-Sliced Design. Границы слоёв реальны, а не декоративны.
diff --git a/alfy-bot-frontend/.env.example b/alfy-bot-frontend/.env.example
index 410f14d..ee9aa35 100644
--- a/alfy-bot-frontend/.env.example
+++ b/alfy-bot-frontend/.env.example
@@ -1,4 +1,5 @@
VITE_API_URL=http://localhost:3002/api
+VITE_MCP_URL=http://localhost:3003/mcp
# Dev auth (no WebApp): VITE_DEV_USE_WIDGET=true|false
# true: Login Widget on /login (backend: BOT_TOKEN for widget validation)
diff --git a/alfy-bot-frontend/src/features/mcp/api/tokens.ts b/alfy-bot-frontend/src/features/mcp/api/tokens.ts
new file mode 100644
index 0000000..6ad4994
--- /dev/null
+++ b/alfy-bot-frontend/src/features/mcp/api/tokens.ts
@@ -0,0 +1,18 @@
+import type { CreatedMcpToken, McpToken } from '../model/types'
+import { api } from '@/api/client'
+
+const path = '/auth/api-tokens'
+
+export async function listTokens(): Promise {
+ const { data } = await api.get(path)
+ return data
+}
+
+export async function createToken(name: string): Promise {
+ const { data } = await api.post(path, { name })
+ return data
+}
+
+export async function revokeToken(id: number): Promise {
+ await api.delete(`${path}/${id}`)
+}
diff --git a/alfy-bot-frontend/src/features/mcp/lib/connection-guide.ts b/alfy-bot-frontend/src/features/mcp/lib/connection-guide.ts
new file mode 100644
index 0000000..7520d3f
--- /dev/null
+++ b/alfy-bot-frontend/src/features/mcp/lib/connection-guide.ts
@@ -0,0 +1,28 @@
+export interface ConnectionGuide {
+ codex: string
+ claudeCode: string
+ generic: string
+}
+
+const singleQuote = /'/g
+
+export function resolveMcpUrl(override: string | undefined, origin: string): string {
+ const url = override?.trim() ? new URL(override.trim()) : new URL('/mcp', origin)
+ if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash) {
+ throw new Error('Адрес MCP должен использовать HTTP или HTTPS без логина и фрагмента')
+ }
+ return url.toString()
+}
+
+function shellQuote(value: string): string {
+ return `'${value.replace(singleQuote, '\'\\\'\'')}'`
+}
+
+export function buildConnectionGuide(url: string): ConnectionGuide {
+ const encodedUrl = JSON.stringify(url)
+ return {
+ codex: `[mcp_servers.alfy]\nurl = ${encodedUrl}\nbearer_token_env_var = "ALFY_MCP_TOKEN"`,
+ claudeCode: `claude mcp add --transport http alfy ${shellQuote(url)} --header 'Authorization: Bearer YOUR_ALFY_TOKEN'`,
+ generic: JSON.stringify({ type: 'http', url, headers: { Authorization: 'Bearer YOUR_ALFY_TOKEN' } }, null, 2),
+ }
+}
diff --git a/alfy-bot-frontend/src/features/mcp/model/types.ts b/alfy-bot-frontend/src/features/mcp/model/types.ts
new file mode 100644
index 0000000..7a1c9f9
--- /dev/null
+++ b/alfy-bot-frontend/src/features/mcp/model/types.ts
@@ -0,0 +1,12 @@
+export interface McpToken {
+ id: number
+ name: string
+ prefix: string
+ created_at: string
+ last_used_at: string | null
+}
+
+export interface CreatedMcpToken {
+ id: number
+ plaintext: string
+}
diff --git a/alfy-bot-frontend/src/features/mcp/model/useMcpTokens.ts b/alfy-bot-frontend/src/features/mcp/model/useMcpTokens.ts
new file mode 100644
index 0000000..552544f
--- /dev/null
+++ b/alfy-bot-frontend/src/features/mcp/model/useMcpTokens.ts
@@ -0,0 +1,78 @@
+import type { CreatedMcpToken, McpToken } from './types'
+import { ref } from 'vue'
+import { createToken, listTokens, revokeToken } from '../api/tokens'
+
+export function useMcpTokens() {
+ const tokens = ref([])
+ const revealed = ref(null)
+ const loading = ref(false)
+ const creating = ref(false)
+ const revokingId = ref(null)
+ const loadError = ref(null)
+ const createError = ref(null)
+ const revokeError = ref(null)
+
+ async function fetchTokens(): Promise {
+ if (loading.value)
+ return
+ loading.value = true
+ loadError.value = null
+ try {
+ tokens.value = await listTokens()
+ }
+ catch {
+ loadError.value = 'Не удалось загрузить список токенов'
+ }
+ finally {
+ loading.value = false
+ }
+ }
+
+ async function refresh(): Promise {
+ if (creating.value || revokingId.value !== null)
+ return
+ await fetchTokens()
+ }
+
+ async function create(name: string): Promise {
+ if (creating.value || loading.value || revokingId.value !== null || !name.trim())
+ return
+ creating.value = true
+ createError.value = null
+ try {
+ revealed.value = await createToken(name.trim())
+ await fetchTokens()
+ }
+ catch {
+ createError.value = 'Не удалось создать токен. Обновите список и отзовите лишний токен, если запрос всё же прошёл.'
+ }
+ finally {
+ creating.value = false
+ }
+ }
+
+ async function revoke(id: number): Promise {
+ if (revokingId.value !== null || loading.value || creating.value)
+ return
+ revokingId.value = id
+ revokeError.value = null
+ try {
+ await revokeToken(id)
+ tokens.value = tokens.value.filter(token => token.id !== id)
+ if (revealed.value?.id === id)
+ revealed.value = null
+ }
+ catch {
+ revokeError.value = 'Не удалось отозвать токен'
+ }
+ finally {
+ revokingId.value = null
+ }
+ }
+
+ function dismissSecret(): void {
+ revealed.value = null
+ }
+
+ return { tokens, revealed, loading, creating, revokingId, loadError, createError, revokeError, refresh, create, revoke, dismissSecret }
+}
diff --git a/alfy-bot-frontend/src/features/mcp/ui/McpConnectionGuide.vue b/alfy-bot-frontend/src/features/mcp/ui/McpConnectionGuide.vue
new file mode 100644
index 0000000..b79862b
--- /dev/null
+++ b/alfy-bot-frontend/src/features/mcp/ui/McpConnectionGuide.vue
@@ -0,0 +1,76 @@
+
+
+
+
+
+ Подключение агента
+
+
+ Сервер MCP: {{ url }}
+
+
+ {{ configError }}
+
+
+
+ Для Codex сохраните пример в ~/.codex/config.toml, задайте переменную окружения перед запуском и проверьте список MCP-инструментов после перезапуска. Для Claude Code замените placeholder токена и выполните команду. Примеры не содержат выданный секрет.
+
- Для Codex сохраните пример в ~/.codex/config.toml, задайте переменную окружения перед запуском и проверьте список MCP-инструментов после перезапуска. Для Claude Code замените placeholder токена и выполните команду. Примеры не содержат выданный секрет.
+ Добавьте секцию Codex в ~/.codex/config.toml или запись alfy в mcpServers файла .mcp.json в корне проекта Claude Code. Существующие настройки сохраните. Выполните команды ниже в Bash или Zsh, затем вставьте токен и нажмите Enter: ввод скрыт и не попадает в историю команд. Запустите агента из этого же терминала; в Claude Code проверьте подключение командой /mcp. Конфигурации используют переменную ALFY_MCP_TOKEN.
-
export ALFY_MCP_TOKEN='YOUR_ALFY_TOKEN'
+
export ALFY_MCP_TOKEN
+read -rs ALFY_MCP_TOKEN
diff --git a/alfy-bot-frontend/tests/features/mcp/connection-guide.spec.ts b/alfy-bot-frontend/tests/features/mcp/connection-guide.spec.ts
index 0e9de08..516b167 100644
--- a/alfy-bot-frontend/tests/features/mcp/connection-guide.spec.ts
+++ b/alfy-bot-frontend/tests/features/mcp/connection-guide.spec.ts
@@ -20,12 +20,12 @@ describe('адрес MCP', () => {
})
describe('инструкции подключения', () => {
- it('не включает реальный секрет и экранирует адрес в TOML и shell', () => {
+ it('не включает реальный секрет и экранирует адрес в TOML и JSON', () => {
const url = 'https://example.com/mcp?name="x"&part=\'y\''
const guide = buildConnectionGuide(url)
expect(guide.codex).toContain('bearer_token_env_var = "ALFY_MCP_TOKEN"')
expect(guide.codex).toContain('name=\\"x\\"')
- expect(guide.claudeCode).toContain('\'\\\'\'')
+ expect(JSON.parse(guide.claudeCode)).toEqual({ mcpServers: { alfy: { type: 'http', url, headers: { Authorization: `Bearer \${ALFY_MCP_TOKEN}` } } } })
expect(guide.generic).toContain('YOUR_ALFY_TOKEN')
expect(JSON.stringify(guide)).not.toContain('secret-from-user')
})
diff --git a/alfy-mcp/README.md b/alfy-mcp/README.md
index ab392ce..f277e44 100644
--- a/alfy-mcp/README.md
+++ b/alfy-mcp/README.md
@@ -49,12 +49,29 @@ url = "https://tracker.rocketup.tech/mcp"
bearer_token_env_var = "ALFY_MCP_TOKEN"
```
-Перед запуском Codex задайте `ALFY_MCP_TOKEN` выданным токеном в окружении. В Claude Code подключите сервер командой, заменив `YOUR_ALFY_TOKEN` на выданный токен:
+В Claude Code добавьте запись `alfy` в `mcpServers` файла `.mcp.json` в корне проекта, сохранив существующие серверы:
+
+```json
+{
+ "mcpServers": {
+ "alfy": {
+ "type": "http",
+ "url": "https://tracker.rocketup.tech/mcp",
+ "headers": { "Authorization": "Bearer ${ALFY_MCP_TOKEN}" }
+ }
+ }
+}
+```
+
+Перед запуском Codex или Claude Code выполните в Bash/Zsh команды ниже, затем вставьте токен и нажмите Enter. Ввод скрыт и не записывается в историю команд. Запустите агент из этого же терминала; в Claude Code проверьте подключение через `/mcp`.
```bash
-claude mcp add --transport http alfy 'https://tracker.rocketup.tech/mcp' --header 'Authorization: Bearer YOUR_ALFY_TOKEN'
+export ALFY_MCP_TOKEN
+read -rs ALFY_MCP_TOKEN
```
+Ссылка на переменную в заголовке поддерживается [Claude Code](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json).
+
Актуальные примеры с адресом текущего окружения доступны в настройках веб-приложения.
Протокол: [MCP Streamable HTTP](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#streamable-http-transport)
From bfee6e0579da0b7c02288ac821e4cc80fd4520bd Mon Sep 17 00:00:00 2001
From: "i.seliverstov"
Date: Fri, 9 Oct 2026 18:36:57 +0500
Subject: [PATCH 4/4] docs: record MCP profile implementation and validation
---
docs/tasks/mcp-profile.md | 103 ++++++++++++++++++++++++++++++++++++++
1 file changed, 103 insertions(+)
create mode 100644 docs/tasks/mcp-profile.md
diff --git a/docs/tasks/mcp-profile.md b/docs/tasks/mcp-profile.md
new file mode 100644
index 0000000..4eb71fa
--- /dev/null
+++ b/docs/tasks/mcp-profile.md
@@ -0,0 +1,103 @@
+# MCP в настройках профиля
+
+**Status:** done
+**Branch:** codex/mcp-profile
+**Worktree:** /Users/v/projects/Alfy/.worktrees/mcp-profile
+**Goal:** Пользователь создаёт токен в настройках, подключает своего агента по инструкции, читает свои задачи через MCP и после отзыва токена теряет доступ с этим токеном.
+**Mode:** interactive
+
+## Context
+- База — актуальный remote main `607eb9bb9e5ed088ba3ef8489f1dcb4d795fdaf3`; пользователь подтвердил main вместо develop.
+- `ApiTokenService` уже создаёт именованные токены, хранит bcrypt-хеш, возвращает список метаданных и отзывает токен с проверкой владельца. Сейчас выдача доступна через Telegram-бота.
+- `SettingsView.vue` содержит настройки аккаунта; HTTP MCP принимает Bearer-токен на `/mcp`.
+- Рабочая копия изолирована от незакоммиченных изменений исходного checkout. Зависимости ещё не установлены, проверки не запускались.
+
+## Design
+Дизайн, цель и план согласованы пользователем; разрешён автоапрув плана.
+
+Секция «MCP и агенты» в настройках с созданием именованного токена, однократным показом секрета и кнопкой копирования. Список содержит имя, префикс, дату создания и последнего использования; отзыв требует явного подтверждения в интерфейсе. Сообщение поясняет, что агент получает доступ к данным пользователя, включая изменения.
+
+Добавить JWT-защищённые REST-методы создания, списка и отзыва поверх существующего `ApiTokenService`. Новых таблиц и отдельной системы авторизации не требуется. Управление токенами недоступно по MCP/API-токену. Команды Telegram и существующие токены продолжают работать.
+
+Инструкция рядом с токенами: подключение по Streamable HTTP, адрес сервера, Bearer-авторизация и копируемые примеры для Codex, Claude Code и универсального клиента. Конфигурации используют placeholder токена; секрет копируется отдельной кнопкой. URL определяется единообразно для окружения; поддержать явный адрес MCP для локальной разработки.
+
+Альтернативы: ссылка на команды Telegram требует перехода в бот и не обеспечивает выдачу на клиенте; отдельные OAuth/scopes расширяют задачу и требуют новой модели доступа. Рекомендуется существующий механизм токенов и небольшой REST/UI слой.
+
+TDD: yes — контракты REST, права владельца и отказ доступа после отзыва; внешний вид проверяется в браузере.
+
+### Invariants
+- IV1 — Пользователь видит и отзывает только свои токены; userId берётся из JWT.
+- IV2 — Plaintext возвращается только при создании, не записывается в постоянное хранилище браузера, URL или логи; список не содержит секрет или хеш.
+- IV3 — Отозванный токен больше не позволяет читать или изменять данные через MCP.
+- IV4 — Ошибки создания, загрузки, отзыва и копирования отображаются пользователю; повторная отправка блокируется на время запроса.
+
+### Assumptions
+- AS1 — Сохраняется существующая модель прав API-токена без сроков действия и scopes.
+
+### Unknowns
+- UK1 — Проверить актуальный синтаксис конфигураций клиентов по официальной документации при подготовке инструкций.
+
+## Plan
+Переиспользовать `ApiTokenService`, JWT guard, общий axios-клиент и существующий ConfirmDialog. Две фазы без миграций и изменений протокола MCP; файлы новых модулей указаны с начальной строкой `:1`.
+
+### PH1 — API управления токенами
+- `alfy-bot/src/modules/auth/api-tokens.controller.ts:1` (create): `ApiTokensController.create(req, dto)`, `list(req)`, `revoke(req, id)` — маршруты IF1, JWT-only guard, числовой ID, `Cache-Control: no-store`; делегирование существующему сервису с `req.user.sub` (IV1–IV3, AS1).
+- `alfy-bot/src/modules/auth/dto/create-api-token.dto.ts:1` (create): `CreateApiTokenDto.name: string` — trim и длина 1–100 символов; не принимать userId из тела.
+- `alfy-bot/src/modules/auth/auth.module.ts:6-39` (modify): регистрация нового контроллера, без изменений сервисов и Telegram-команд.
+- `alfy-bot/test/api-tokens.e2e-spec.ts:1` (create): failing tests перед реализацией через существующий `createTestApp`; создание, whitelist ответа, список только своих токенов, чужой/повторный отзыв, невалидное имя/ID, отказ без JWT и с API-токеном на всех методах; API-токен читает задачи до отзыва и получает 401 после него.
+- Commit: `feat(auth): expose profile token management API`.
+
+### PH2 — Настройки и подключение агентов
+- `alfy-bot-frontend/src/features/mcp/api/tokens.ts:1` (create): `listTokens(): Promise`, `createToken(name: string): Promise`, `revokeToken(id: number): Promise` через существующий `api` (IF1).
+- `alfy-bot-frontend/src/features/mcp/model/types.ts:1` (create): типы ответов IF1.
+- `alfy-bot-frontend/src/features/mcp/model/useMcpTokens.ts:1` (create): локальное состояние списка и однократно показанного секрета, независимые ошибки загрузки/создания/отзыва, блокировка повторных команд; успешная выдача не теряет секрет при ошибке обновления списка (IV2, IV4).
+- `alfy-bot-frontend/src/features/mcp/ui/McpSettings.vue:1` (create): именованная форма, копирование секрета, список и ConfirmDialog отзыва; ошибки clipboard и возможность вручную скопировать текст; очищать показанный секрет после его отзыва.
+- `alfy-bot-frontend/src/features/mcp/ui/McpConnectionGuide.vue:1` (create): адрес, инструкции и копируемые конфигурации без реального секрета; проверить синтаксис Codex и Claude Code по официальным источникам (UK1).
+- `alfy-bot-frontend/src/features/mcp/lib/connection-guide.ts:1` (create): `resolveMcpUrl(override: string | undefined, origin: string): string`, `buildConnectionGuide(url: string): ConnectionGuide`; явный `VITE_MCP_URL` имеет приоритет, иначе `/mcp` на текущем origin. Передавать окружение из UI, а не читать его внутри функций (GPC1).
+- `alfy-bot-frontend/src/views/SettingsView.vue:164-180` (modify): импорт и размещение секции.
+- `alfy-bot-frontend/.env.example:1-2`, `alfy-bot-frontend/src/vite-env.d.ts:1` (modify): локальный `VITE_MCP_URL=http://localhost:3003/mcp` и тип конфигурации; production same-origin работает без новой настройки сборки.
+- `alfy-bot-frontend/tests/features/mcp/McpSettings.spec.ts:1`, `alfy-bot-frontend/tests/features/mcp/connection-guide.spec.ts:1` (create): выдача/однократность/отзыв/ошибки/повторные клики, отсутствие секрета в storage и инструкциях, адреса и экранирование конфигураций; failing tests для детерминированных контрактов перед реализацией.
+- `alfy-bot-frontend/tests/views/SettingsView.spec.ts:1-40` (modify): проверка встраивания секции с изолированным мокированием API.
+- `alfy-mcp/README.md:7-42`, `CLAUDE.md:11-60` (modify): получение и отзыв через настройки, подключение по HTTP; сохранять поддержку Telegram и stdio. `README.md` проверить на необходимость правок после реализации.
+- Commit: `feat(settings): add MCP tokens and agent setup guide`.
+
+### Interfaces
+- IF1 — JWT-only `/api/auth/api-tokens`: GET → `McpToken[]`; POST `{ name: string }` → 201 `{ id: number, plaintext: string }`; DELETE `/:id` → 204. `McpToken = { id: number; name: string; prefix: string; created_at: string; last_used_at: string | null }`; даты ISO 8601. Валидация → 400, отсутствие JWT → 401, чужой или уже отозванный ID → 404.
+
+### Interface graph
+- PH1 -> IF1 @ alfy-bot/src/modules/auth/api-tokens.controller.ts, alfy-bot/src/modules/auth/dto/create-api-token.dto.ts, alfy-bot/src/modules/auth/auth.module.ts, alfy-bot/test/api-tokens.e2e-spec.ts
+- PH2 IF1 -> @ alfy-bot-frontend/src/features/mcp/, alfy-bot-frontend/src/views/SettingsView.vue, alfy-bot-frontend/src/vite-env.d.ts, alfy-bot-frontend/.env.example, alfy-bot-frontend/tests/features/mcp/, alfy-bot-frontend/tests/views/SettingsView.spec.ts, alfy-mcp/README.md, CLAUDE.md
+
+### Проверки и риски
+- Установить зависимости по lockfile отдельно в worktree; сначала baseline существующих auth/token и SettingsView тестов, затем RED/GREEN новых контрактов, связанные тесты и сборки backend/frontend.
+- Сквозной сценарий из Verify обязателен дополнительно к unit/e2e API; проверить UI на мобильной и настольной ширине. Реальные внешние приложения агентов не считать проверенными по одному только MCP SDK.
+- RK1 — Потерянный ответ выдачи нельзя восстановить из хеша: не делать автоматический retry POST; после сетевой ошибки предложить обновить список и отозвать лишний токен.
+- RK2 — Неверный адрес окружения ломает подключение: тестировать same-origin и явный локальный URL, неподдерживаемый URL показывать как ошибку конфигурации.
+- Совместимость: только добавление REST/UI; формат токенов и команды бота неизменны. Откат — revert двух commits, существующие данные токенов остаются пригодны для бота.
+
+## Verify
+Result: passed.
+- CK1 (IV1, IF1) — чужой/повторный отзыв, список владельца, отсутствие JWT и API-токен вместо JWT — held: свежий `npm run test:e2e -- --runInBand api-tokens.e2e-spec.ts`, 14/14.
+- CK2 (IV2) — plaintext в списке/после перезагрузки — held: whitelist e2e и реальная перезагрузка браузера; копирование показало успешный статус, секрет исчез после reload.
+- CK3 (IV3) — отзыв не закрывает MCP-доступ — held: созданный в браузере токен прочитал `MCP profile smoke task` через SDK/Streamable HTTP; после отзыва через ConfirmDialog тот же `list_tasks` вернул `isError: true`, `REST 401: Unauthorized`.
+- CK4 (IV4) — ошибка обновления списка теряет токен, clipboard failure, повторный submit — held: свежие 17/17 frontend tests; конкурирующие refresh/mutations заблокированы.
+- CK5 (UK1) — конфигурации расходятся с клиентами — held: проверены официальные https://developers.openai.com/learn/docs-mcp и https://docs.anthropic.com/en/docs/claude-code/mcp ; URL/escaping проверены тестами. Нативные приложения Codex/Claude Code не запускались; реальный MCP-протокол проверен SDK.
+- CK6 — мобильная страница переполняется — held: браузер 390×844, scrollWidth=clientWidth=379; проверен desktop и сохранён screenshot.
+- Сборки backend/frontend/MCP прошли; 20 существующих auth-тестов, 7 story-sprint e2e и 152 MCP-теста прошли.
+Smoke: браузер `localhost:5178/settings` → тестовая БД в памяти на 3302 → MCP на 3303 → успешное чтение → отзыв → отказ; цель наблюдалась полностью на локальном окружении.
+Notes: backend `npm ci` не проходит из-за существующего рассогласования lockfile (encoding); зависимости установлены локально через `npm install --package-lock=false`, lockfile не изменён. Общий frontend lint сообщил 2047 проблем; сравнение с чистым baseline не выполнялось; ESLint новых файлов и typecheck прошли. Временный стенд требовал CORS до app.init; production-код для этого не менялся.
+
+## Execution
+- [x] PH1 — API управления токенами: `12950d3`.
+- [x] PH2 — настройки и инструкции: `84333db`.
+
+## Conclusion
+Цель достигнута на локальном окружении: выдача в браузере → чтение через MCP SDK → отзыв в браузере → отказ доступа. Итоговый код `49a083e`; ветка не опубликована и не слита.
+- IV1–IV4 — подтверждены CK1–CK4; AS1 сохранена без изменений модели токенов.
+- UK1 закрыт: примеры сверены с официальными источниками, Claude Code использует `${ALFY_MCP_TOKEN}` в `.mcp.json`. Нативные приложения агентов не запускались; проверен реальный HTTP MCP-клиент SDK.
+- Независимое ревью выявило сохранение токена в shell history при ручной подстановке в команду; исправлено в `49a083e`. Повторное ревью не выявило замечаний высокой уверенности. Регрессионный тест сначала упал на старом формате команды, затем прошёл на JSON; скрытый ввод и экспорт проверены в Bash/Zsh.
+- Проверки после исправления: 17 frontend-тестов и build прошли, scoped lint прошёл; повторный просмотр браузера подтвердил итоговые инструкции.
+
+### Deviations from plan
+- Вместо CLI-команды Claude Code показан фрагмент `.mcp.json` со ссылкой на переменную окружения: исключена вставка секрета в историю shell и аргументы процесса установки.
+- Использована `.tmp/` вместо `tmp/` для проверочного стенда: этот каталог уже игнорируется репозиторием. Стенд и временные секреты удаляются после проверки.