546 lines
35 KiB
Python
546 lines
35 KiB
Python
"""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
|