second phase of the project management dashboard

This commit is contained in:
Joren de Graaf
2026-10-13 20:37:56 +02:00
parent 3559b367e6
commit e4419b4a18
27 changed files with 1317 additions and 63 deletions
View File
+545
View File
@@ -0,0 +1,545 @@
"""Streamable HTTP MCP server for project management. Run on port 8766."""
import os
from datetime import date
from typing import Any, Literal
from urllib.parse import urlsplit
from uuid import UUID
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
import django
django.setup()
from asgiref.sync import sync_to_async
from django.conf import settings
from django.contrib.auth import get_user_model
from django.core.exceptions import PermissionDenied, ValidationError
from django.db.models import Q
from django.db import transaction
from django.http import Http404
from django.test.client import RequestFactory
from oauth2_provider.oauth2_backends import OAuthLibCore
from mcp.server.auth.middleware.auth_context import get_access_token
from mcp.server.auth.provider import AccessToken, TokenVerifier
from mcp.server.auth.routes import create_protected_resource_routes
from mcp.server.auth.settings import AuthSettings
from mcp.server.mcpserver import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
from mcp.server.transport_security import TransportSecuritySettings
from pydantic import AnyHttpUrl
from projects import services
from projects.models import Activity, Card, CardComment, CardRevision, Column, Project, Tag
def _verified(raw):
resource = urlsplit(settings.MCP_PUBLIC_URL)
request = RequestFactory().get(resource.path, HTTP_HOST=resource.netloc,
HTTP_AUTHORIZATION=f'Bearer {raw}', secure=resource.scheme == 'https')
valid, result = OAuthLibCore().verify_request(request, scopes=[])
if not valid or not getattr(result, 'user', None):
return None
return {'user_id': result.user.pk, 'scopes': list(result.scopes), 'expires_at': getattr(result, 'expires_at', None)}
class OAuthTokenVerifier(TokenVerifier):
async def verify_token(self, token: str) -> AccessToken | None:
if len(token) > 512:
return None
info = await sync_to_async(_verified)(token)
if not info:
return None
return AccessToken(token=token, client_id='dashboard', scopes=info['scopes'], subject=str(info['user_id']))
def _actor(scope='projects:read'):
access = get_access_token()
if access is None or scope not in access.scopes:
raise ToolError(f'permission_denied: {scope} authorization required')
return get_user_model().objects.get(pk=access.subject)
def _project(user, value, write=False):
try:
identifier = UUID(value)
except (ValueError, TypeError):
matches = list(services.accessible(user).filter(name__iexact=value)[:3])
if len(matches) != 1:
raise ToolError(f'ambiguous_project: supply a project UUID; candidates: {[str(p.pk) for p in matches]}')
identifier = matches[0].pk
return services.project_for(user, identifier, write=write)
def _card(user, value, write=False):
return services.card_for(user, UUID(value), write=write)
def _project_data(project):
cards = Card.objects.filter(project=project, archived=False)
return {'id': str(project.pk), 'name': project.name, 'slug': project.slug, 'description': project.description,
'git_repository_url': project.git_repository_url or None, 'archived': project.archived,
'card_count': cards.count(), 'done_count': cards.filter(column__is_done=True).count()}
def _card_data(card):
return {'id': str(card.pk), 'project_id': str(card.project_id), 'column_id': str(card.column_id), 'title': card.title,
'markdown': card.description_markdown, 'priority': card.priority, 'card_type': card.card_type,
'revision': card.revision, 'position': card.position, 'is_blocked': card.is_blocked,
'blocked_reason': card.blocked_reason, 'archived': card.archived,
'assignee_id': card.assignee_id,
'tags': [{'id': tag.pk, 'name': tag.name} for tag in card.tags.all()],
'due_date': card.due_date.isoformat() if card.due_date else None,
'completed_at': card.completed_at.isoformat() if card.completed_at else None,
'created_at': card.created_at.isoformat(), 'updated_at': card.updated_at.isoformat(),
'url': f'{settings.OAUTH_ISSUER_URL.rstrip("/")}/projects/cards/{card.pk}/'}
def _column_data(column):
return {'id': str(column.pk), 'name': column.name, 'position': column.position,
'color': column.color, 'is_default': column.is_default, 'is_done': column.is_done}
def _safe(operation):
try:
return operation()
except (Http404, Project.DoesNotExist, Card.DoesNotExist, Column.DoesNotExist, CardRevision.DoesNotExist, Tag.DoesNotExist, get_user_model().DoesNotExist):
raise ToolError('not_found: project or card is unavailable')
except PermissionDenied:
raise ToolError('permission_denied: write access required')
except ValidationError as exc:
raise ToolError(f'invalid_input: {exc}')
except services.RevisionConflict as exc:
raise ToolError(f'revision_conflict: current revision is {exc.current}')
except ValueError as exc:
raise ToolError(f'invalid_input: {exc}')
def create_server():
server = MCPServer('Common Ground Projects', description='Projects, Kanban cards, and Markdown specifications.',
token_verifier=OAuthTokenVerifier(), auth=AuthSettings(
issuer_url=AnyHttpUrl(settings.OAUTH_ISSUER_URL),
resource_server_url=AnyHttpUrl(settings.MCP_PUBLIC_URL), required_scopes=[], validate_token_resource=False))
@server.tool(structured_output=True, description='List projects accessible to the connected user, with counts and repository metadata.')
async def projects_list(limit: int = 50, offset: int = 0) -> dict[str, Any]:
def run():
user = _actor()
qs = services.accessible(user).filter(archived=False).order_by('name')
return {'items': [_project_data(p) for p in qs[offset:offset + min(max(limit, 1), 100)]], 'total': qs.count()}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Get a project, its default column, counts, and Git repository URL. The URL is metadata only.')
async def projects_get(project: str) -> dict[str, Any]:
def run():
p = _project(_actor(), project)
return {**_project_data(p), 'default_column_id': str(p.board.columns.get(is_default=True, archived=False).pk)}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Update project name, description, or HTTPS Git repository metadata.')
async def projects_update(project: str, name: str | None = None, description: str | None = None, git_repository_url: str | None = None) -> dict[str, Any]:
def run():
user = _actor('projects:write')
p = _project(user, project, write=True)
if name is not None: p.name = name
if description is not None: p.description = description
if git_repository_url is not None: p.git_repository_url = git_repository_url
p.full_clean()
if p.git_repository_url and not p.git_repository_url.startswith('https://'):
raise ValidationError('Use an HTTPS repository URL.')
p.save()
Activity.objects.create(project=p, actor=user, action='project.updated', origin='mcp')
return _project_data(p)
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Archive a project without deleting its board or cards.')
async def projects_archive(project: str) -> dict[str, Any]:
def run():
user = _actor('projects:write')
p = _project(user, project, write=True)
p.archived = True; p.save(update_fields=['archived'])
Activity.objects.create(project=p, actor=user, action='project.archived', origin='mcp')
return _project_data(p)
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Get project progress and workload by priority with repository metadata.')
async def projects_summary(project: str) -> dict[str, Any]:
def run():
p = _project(_actor(), project)
cards = Card.objects.filter(project=p, archived=False)
return {**_project_data(p), 'by_priority': {priority: cards.filter(priority=priority).count() for priority in ('high', 'medium', 'low')}, 'blocked_count': cards.filter(is_blocked=True).count()}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Search accessible project names and descriptions.')
async def projects_search(query: str, limit: int = 50) -> dict[str, Any]:
def run():
qs = services.accessible(_actor()).filter(Q(name__icontains=query) | Q(description__icontains=query), archived=False)[:min(max(limit, 1), 100)]
return {'items': [_project_data(p) for p in qs]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Create a project and seed editable To-do, In Progress, and Done columns.')
async def projects_create(name: str, description: str = '', git_repository_url: str = '') -> dict[str, Any]:
return await sync_to_async(lambda: _safe(lambda: _project_data(services.create_project(_actor('projects:write'), name=name, description=description, git_repository_url=git_repository_url))))()
@server.tool(structured_output=True, description='List active columns for a project, including default and completion flags.')
async def columns_list(project: str) -> dict[str, Any]:
def run():
p = _project(_actor(), project)
return {'items': [_column_data(c) for c in p.board.columns.filter(archived=False)]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Get a project board with its columns and card summaries.')
async def boards_get(project: str) -> dict[str, Any]:
def run():
p = _project(_actor(), project)
return {'project': _project_data(p), 'columns': [{**_column_data(c), 'cards': [_card_data(card) for card in c.cards.filter(archived=False)[:100]]} for c in p.board.columns.filter(archived=False)]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Create an editable Kanban column in a project.')
async def columns_create(project: str, name: str, color: str = '#315d4d', is_done: bool = False) -> dict[str, Any]:
def run():
p = _project(_actor('projects:write'), project, write=True)
column = Column(board=p.board, name=name, color=color, is_done=is_done, position=p.board.columns.count())
column.full_clean(); column.save()
return _column_data(column)
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Rename or recolor a column, or change its completed state.')
async def columns_update(column_id: str, name: str | None = None, color: str | None = None, is_done: bool | None = None) -> dict[str, Any]:
def run():
column = Column.objects.get(pk=UUID(column_id))
return _column_data(services.update_column(_actor('projects:write'), column, name=name, color=color, is_done=is_done, origin='mcp'))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Choose the one default destination column for new cards.')
async def columns_set_default(column_id: str) -> dict[str, Any]:
def run():
column = Column.objects.get(pk=UUID(column_id))
return _column_data(services.set_default(_actor('projects:write'), column))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Reorder active columns by supplying every column UUID exactly once.')
async def columns_reorder(project: str, column_ids: list[str]) -> dict[str, Any]:
def run():
user = _actor('projects:write'); p = _project(user, project, write=True)
services.reorder_columns(user, p, column_ids)
return {'items': [_column_data(c) for c in p.board.columns.filter(archived=False)]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Archive an empty, non-default column.')
async def columns_archive(column_id: str) -> dict[str, Any]:
def run():
column = Column.objects.get(pk=UUID(column_id))
services.archive_column(_actor('projects:write'), column)
return {'id': str(column.pk), 'archived': True}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Create a card in the project default column with Medium priority unless specified.')
async def cards_create(project: str, title: str, markdown: str = '', priority: Literal['low', 'medium', 'high'] = 'medium', card_type: Literal['feature', 'bug', 'task', 'research', 'idea'] = 'task', column_id: str | None = None, idempotency_key: str | None = None) -> dict[str, Any]:
def run():
user = _actor('projects:write')
p = _project(user, project, write=True)
column = Column.objects.get(pk=UUID(column_id)) if column_id else None
return _card_data(services.create_card(user, p, title=title, markdown=markdown, priority=priority, card_type=card_type, column=column, origin='mcp', idempotency_key=idempotency_key))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Create a Markdown specification card; the configured default column and Medium priority are used if omitted.')
async def specs_create(project: str, title: str, markdown: str, priority: Literal['low', 'medium', 'high'] = 'medium', column_id: str | None = None, idempotency_key: str | None = None) -> dict[str, Any]:
return await cards_create(project, title, markdown, priority, 'feature', column_id, idempotency_key)
@server.tool(structured_output=True, description='Get full card details including exact raw Markdown and revision.')
async def cards_get(card_id: str) -> dict[str, Any]:
return await sync_to_async(lambda: _safe(lambda: _card_data(_card(_actor(), card_id))))()
@server.tool(structured_output=True, description='Update card fields; supply the expected revision to prevent lost edits.')
async def cards_update(card_id: str, expected_revision: int, title: str | None = None, markdown: str | None = None, priority: Literal['low', 'medium', 'high'] | None = None, card_type: Literal['feature', 'bug', 'task', 'research', 'idea'] | None = None, due_date: str | None = None, is_blocked: bool | None = None, blocked_reason: str | None = None) -> dict[str, Any]:
def run():
user = _actor('projects:write')
card = _card(user, card_id, write=True)
values = {'title': title, 'description_markdown': markdown, 'priority': priority, 'card_type': card_type, 'is_blocked': is_blocked, 'blocked_reason': blocked_reason}
values = {key: value for key, value in values.items() if value is not None}
if due_date is not None:
values['due_date'] = date.fromisoformat(due_date) if due_date else None
return _card_data(services.update_card(user, card, expected_revision=expected_revision, origin='mcp', **values))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List cards in an accessible project; filter by priority, column, or archived state.')
async def cards_list(project: str, priority: Literal['low', 'medium', 'high'] | None = None, card_type: Literal['feature', 'bug', 'task', 'research', 'idea'] | None = None, column_id: str | None = None, tag_id: int | None = None, assignee_id: int | None = None, archived: bool = False, limit: int = 50, offset: int = 0) -> dict[str, Any]:
def run():
p = _project(_actor(), project)
qs = Card.objects.filter(project=p, archived=archived)
if priority: qs = qs.filter(priority=priority)
if card_type: qs = qs.filter(card_type=card_type)
if column_id: qs = qs.filter(column_id=UUID(column_id))
if tag_id: qs = qs.filter(tags__pk=tag_id)
if assignee_id: qs = qs.filter(assignee_id=assignee_id)
return {'items': [_card_data(c) for c in qs[offset:offset + min(max(limit, 1), 100)]], 'total': qs.count()}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Search card titles and full Markdown within an accessible project.')
async def cards_search(project: str, query: str, priority: Literal['low', 'medium', 'high'] | None = None, limit: int = 50) -> dict[str, Any]:
def run():
p = _project(_actor(), project)
qs = Card.objects.filter(project=p, archived=False).filter(Q(title__icontains=query) | Q(description_markdown__icontains=query))
if priority: qs = qs.filter(priority=priority)
return {'items': [_card_data(c) for c in qs[:min(max(limit, 1), 100)]]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Archive a card without permanently deleting its content or history.')
async def cards_archive(card_id: str, expected_revision: int) -> dict[str, Any]:
def run():
user = _actor('projects:write'); card = _card(user, card_id, write=True)
return _card_data(services.update_card(user, card, expected_revision=expected_revision, archived=True, origin='mcp'))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Restore an archived card to its existing column.')
async def cards_restore(card_id: str, expected_revision: int) -> dict[str, Any]:
def run():
user = _actor('projects:write'); card = _card(user, card_id, write=True)
return _card_data(services.update_card(user, card, expected_revision=expected_revision, archived=False, origin='mcp'))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Add a progress comment to a card.')
async def cards_add_comment(card_id: str, body: str) -> dict[str, Any]:
def run():
if not body.strip(): raise ValidationError('Comment is required.')
user = _actor('projects:write'); card = _card(user, card_id, write=True)
note = CardComment.objects.create(card=card, author=user, body=body)
Activity.objects.create(project=card.project, card=card, actor=user, action='card.commented', origin='mcp')
return {'id': note.pk, 'card_id': str(card.pk), 'body': note.body, 'created_at': note.created_at.isoformat()}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List progress comments on a card.')
async def cards_list_comments(card_id: str, limit: int = 50) -> dict[str, Any]:
def run():
card = _card(_actor(), card_id)
return {'items': [{'id': c.pk, 'body': c.body, 'author_id': c.author_id, 'created_at': c.created_at.isoformat()} for c in card.comments.order_by('-created_at')[:min(max(limit, 1), 100)]]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List card activity and revision numbers.')
async def cards_history(card_id: str, limit: int = 50) -> dict[str, Any]:
def run():
card = _card(_actor(), card_id)
return {'items': [{'action': a.action, 'detail': a.detail, 'origin': a.origin, 'created_at': a.created_at.isoformat()} for a in card.activity.all()[:min(max(limit, 1), 100)]], 'revision': card.revision}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Replace raw Markdown only when expected_revision matches the current card revision.')
async def specs_replace(card_id: str, markdown: str, expected_revision: int) -> dict[str, Any]:
def run():
user = _actor('projects:write')
card = _card(user, card_id, write=True)
return _card_data(services.update_card(user, card, expected_revision=expected_revision, description_markdown=markdown, origin='mcp'))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Append raw Markdown with an optimistic revision check.')
async def specs_append(card_id: str, markdown: str, expected_revision: int) -> dict[str, Any]:
def run():
user = _actor('projects:write')
card = _card(user, card_id, write=True)
return _card_data(services.update_card(user, card, expected_revision=expected_revision, description_markdown=card.description_markdown + markdown, origin='mcp'))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Set one of the three supported card priorities without changing its column.')
async def cards_set_priority(card_id: str, priority: Literal['low', 'medium', 'high'], expected_revision: int) -> dict[str, Any]:
def run():
user = _actor('projects:write')
card = _card(user, card_id, write=True)
return _card_data(services.update_card(user, card, expected_revision=expected_revision, priority=priority, origin='mcp'))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Move a card to another column in the same project, optionally to a zero-based position.')
async def cards_move(card_id: str, column_id: str, position: int | None = None) -> dict[str, Any]:
def run():
user = _actor('projects:write')
return _card_data(services.move_card(user, _card(user, card_id, write=True), Column.objects.get(pk=UUID(column_id)), position, origin='mcp'))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Reorder a card within its current column using a zero-based position.')
async def cards_reorder(card_id: str, position: int) -> dict[str, Any]:
def run():
user = _actor('projects:write'); card = _card(user, card_id, write=True)
return _card_data(services.move_card(user, card, card.column, position, origin='mcp'))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Duplicate a card and its raw Markdown into the same project and column.')
async def cards_duplicate(card_id: str) -> dict[str, Any]:
def run():
user = _actor('projects:write'); card = _card(user, card_id, write=True)
copy = services.create_card(user, card.project, title=f'{card.title} (copy)', markdown=card.description_markdown, column=card.column, priority=card.priority, card_type=card.card_type, origin='mcp')
copy.tags.set(card.tags.all())
return _card_data(copy)
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Replace a card’s tags with existing tag IDs from the same project.')
async def cards_set_tags(card_id: str, tag_ids: list[int]) -> dict[str, Any]:
def run():
user = _actor('projects:write'); card = _card(user, card_id, write=True)
tags = list(Tag.objects.filter(project=card.project, pk__in=tag_ids))
if len(tags) != len(set(tag_ids)): raise ValidationError('All tags must belong to this project.')
card.tags.set(tags)
Activity.objects.create(project=card.project, card=card, actor=user, action='card.tags_changed', origin='mcp')
return {**_card_data(card), 'tags': [{'id': t.pk, 'name': t.name} for t in tags]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Assign a card to a user who has access to its project, or clear assignment.')
async def cards_set_assignee(card_id: str, user_id: int | None = None) -> dict[str, Any]:
def run():
user = _actor('projects:write'); card = _card(user, card_id, write=True)
assignee = get_user_model().objects.get(pk=user_id) if user_id is not None else None
services.set_assignee(user, card, assignee, origin='mcp')
return {**_card_data(card), 'assignee_id': card.assignee_id}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List unfinished cards grouped by their exact High, Medium, and Low priorities.')
async def cards_list_by_priority(project: str, limit: int = 100) -> dict[str, Any]:
def run():
p = _project(_actor(), project)
cards = Card.objects.filter(project=p, archived=False, column__is_done=False)[:min(max(limit, 1), 100)]
return {priority: [_card_data(c) for c in cards if c.priority == priority] for priority in ('high', 'medium', 'low')}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List tags in an accessible project.')
async def tags_list(project: str) -> dict[str, Any]:
def run():
p = _project(_actor(), project)
return {'items': [{'id': t.pk, 'name': t.name} for t in Tag.objects.filter(project=p).order_by('name')]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Create a tag within a project.')
async def tags_create(project: str, name: str) -> dict[str, Any]:
def run():
p = _project(_actor('projects:write'), project, write=True)
tag = Tag(project=p, name=name); tag.full_clean(); tag.save()
return {'id': tag.pk, 'name': tag.name}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Rename a tag in a project you may edit.')
async def tags_update(tag_id: int, name: str) -> dict[str, Any]:
def run():
tag = Tag.objects.get(pk=tag_id)
services.project_for(_actor('projects:write'), tag.project_id, write=True)
tag.name = name; tag.full_clean(); tag.save()
return {'id': tag.pk, 'name': tag.name}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Show the connected account without exposing credentials.')
async def users_me() -> dict[str, Any]:
def run():
user = _actor()
return {'id': user.pk, 'username': user.get_username(), 'email': user.email}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List users eligible to be assigned cards in a project.')
async def users_list_assignable(project: str) -> dict[str, Any]:
def run():
p = _project(_actor(), project)
ids = {p.owner_id, *p.memberships.values_list('user_id', flat=True)}
return {'items': [{'id': user.pk, 'username': user.get_username()} for user in get_user_model().objects.filter(pk__in=ids).order_by('username')]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List activity across projects visible to the connected user.')
async def activity_list(limit: int = 50) -> dict[str, Any]:
def run():
events = Activity.objects.filter(project__in=services.accessible(_actor())).order_by('-created_at')[:min(max(limit, 1), 100)]
return {'items': [{'project_id': str(e.project_id), 'card_id': str(e.card_id) if e.card_id else None, 'action': e.action, 'detail': e.detail, 'origin': e.origin, 'created_at': e.created_at.isoformat()} for e in events]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List Markdown versions of a card, newest first.')
async def specs_versions(card_id: str, limit: int = 50) -> dict[str, Any]:
def run():
card = _card(_actor(), card_id)
return {'items': [{'revision': v.revision, 'markdown': v.markdown, 'created_at': v.created_at.isoformat()} for v in card.revisions.order_by('-revision')[:min(max(limit, 1), 100)]]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Get full exact Markdown and revision for a specification card.')
async def specs_get(card_id: str) -> dict[str, Any]:
return await cards_get(card_id)
@server.tool(structured_output=True, description='Restore an earlier Markdown version while retaining revision history.')
async def specs_restore_version(card_id: str, revision: int, expected_revision: int) -> dict[str, Any]:
def run():
user = _actor('projects:write'); card = _card(user, card_id, write=True)
version = CardRevision.objects.get(card=card, revision=revision)
return _card_data(services.update_card(user, card, expected_revision=expected_revision, description_markdown=version.markdown, origin='mcp'))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Suggest actionable cards using live columns, priority, due date, and explicit blockers. Does not change any card.')
async def planning_next(project: str | None = None, limit: int = 20) -> dict[str, Any]:
def run():
user = _actor()
projects = services.accessible(user).filter(archived=False)
if project: projects = projects.filter(pk=_project(user, project).pk)
cards = Card.objects.filter(project__in=projects, archived=False, column__is_done=False).select_related('project', 'column')
ranked = sorted(cards, key=lambda c: (c.is_blocked, c.column.is_default, {'high': 0, 'medium': 1, 'low': 2}[c.priority], c.due_date or date.max, c.created_at))
return {'items': [{**_card_data(c), 'project_name': c.project.name, 'git_repository_url': c.project.git_repository_url or None} for c in ranked[:min(max(limit, 1), 100)]]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Summarize open work by project, column, and priority with Git repository metadata.')
async def planning_overview() -> dict[str, Any]:
def run():
items = []
for p in services.accessible(_actor()).filter(archived=False):
cards = Card.objects.filter(project=p, archived=False)
items.append({**_project_data(p), 'columns': [{**_column_data(c), 'count': cards.filter(column=c).count()} for c in p.board.columns.filter(archived=False)], 'priorities': {key: cards.filter(priority=key).count() for key in ('high', 'medium', 'low')}})
return {'items': items}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List only cards explicitly marked blocked, with their stated reasons.')
async def planning_blocked(limit: int = 50) -> dict[str, Any]:
def run():
cards = Card.objects.filter(project__in=services.accessible(_actor()), archived=False, is_blocked=True)[:min(max(limit, 1), 100)]
return {'items': [_card_data(c) for c in cards]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List recent project and card changes visible to the connected user.')
async def planning_recent(limit: int = 50) -> dict[str, Any]:
def run():
events = Activity.objects.filter(project__in=services.accessible(_actor())).order_by('-created_at')[:min(max(limit, 1), 100)]
return {'items': [{'project_id': str(e.project_id), 'card_id': str(e.card_id) if e.card_id else None, 'action': e.action, 'detail': e.detail, 'origin': e.origin, 'created_at': e.created_at.isoformat()} for e in events]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Summarize outstanding High, Medium, and Low cards without changing priorities.')
async def planning_priorities() -> dict[str, Any]:
def run():
cards = Card.objects.filter(project__in=services.accessible(_actor()), archived=False, column__is_done=False)
return {'high': cards.filter(priority='high').count(), 'medium': cards.filter(priority='medium').count(), 'low': cards.filter(priority='low').count()}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List unfinished cards grouped by priority across accessible projects.')
async def planning_backlog(limit: int = 100) -> dict[str, Any]:
def run():
cards = Card.objects.filter(project__in=services.accessible(_actor()), archived=False, column__is_done=False)[:min(max(limit, 1), 100)]
return {priority: [_card_data(c) for c in cards if c.priority == priority] for priority in ('high', 'medium', 'low')}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Search accessible projects and cards. Results include only data the connected user may read.')
async def search_global(query: str, limit: int = 50) -> dict[str, Any]:
def run():
user = _actor()
projects = services.accessible(user).filter(Q(name__icontains=query) | Q(description__icontains=query))[:min(max(limit, 1), 100)]
cards = Card.objects.filter(project__in=services.accessible(user), archived=False).filter(Q(title__icontains=query) | Q(description_markdown__icontains=query))[:min(max(limit, 1), 100)]
return {'projects': [_project_data(p) for p in projects], 'cards': [_card_data(c) for c in cards]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Report supported MCP tools, scopes, and result limits.')
async def system_capabilities() -> dict[str, Any]:
_actor()
return {'scopes': ['projects:read', 'projects:write'], 'max_page_size': 100, 'version': '0.2', 'transport': 'streamable_http'}
return server
app = create_server().streamable_http_app(
streamable_http_path='/mcp', stateless_http=True, json_response=True,
transport_security=TransportSecuritySettings(
allowed_hosts=[urlsplit(settings.MCP_PUBLIC_URL).netloc, '127.0.0.1:*', 'localhost:*'],
allowed_origins=[f'{urlsplit(settings.MCP_PUBLIC_URL).scheme}://{urlsplit(settings.MCP_PUBLIC_URL).netloc}', 'https://chatgpt.com', 'http://127.0.0.1:*', 'http://localhost:*'],
),
)
metadata_route = create_protected_resource_routes(
resource_url=AnyHttpUrl(settings.MCP_PUBLIC_URL),
authorization_servers=[AnyHttpUrl(settings.OAUTH_ISSUER_URL)],
scopes_supported=['projects:read', 'projects:write'],
)[0]
for index, route in enumerate(app.router.routes):
if getattr(route, 'path', None) == metadata_route.path:
app.router.routes[index] = metadata_route
break