Compare commits
1
Commits
3a12d56f8b
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
2a6450b416 |
@@ -26,6 +26,8 @@ The Documentation page provides folder navigation, a sanitized Markdown view, se
|
||||
|
||||
Read-only MCP tools are `docs_list`, `docs_search`, `docs_read`, `docs_history`, and `docs_diff`. They use existing `projects:read` authorization and project membership. Search results return short snippets; reads return at most 250 lines or 30,000 characters with a continuation cue. Revisions must be retained commits for the requested path. MCP never returns Git credentials and does not accept arbitrary repository URLs or local filesystem paths. Codex working directly in a local checkout should read `docs/` there; remote clients use MCP.
|
||||
|
||||
`docs_sync(project, expected_remote_commit?)` lets a client with `projects:write` scope and project edit access request the same bounded refresh as the authenticated UI button. It returns `completed`, `already_current`, `in_progress`, or `failed` with the observed remote and indexed commits, document count, timestamps, safe error, and cooldown hint. `expected_remote_commit` must be a full Git hash; a different observed remote commit is reported as a failed expectation even if the new index was committed. Calls within the 30-second manual cooldown do not fetch again. A successful index refresh does not advance the separate documentation accuracy audit. After `completed`, clients can call `docs_list` or `docs_read` for the returned indexed commit.
|
||||
|
||||
## Recovery and rollback
|
||||
|
||||
If fetches fail, check the configured host allowlist, the repository's default branch and access, private credential scope, and mirror permissions. The last good index remains available. A subsequent successful refresh atomically replaces it, including deletions. To rebuild a corrupted mirror, stop both services, move only that project's UUID-named mirror directory aside, then refresh. Keep its old directory until the new index is verified if historical reads matter. Deleting a project removes its mirror after the database transaction commits. Database migrations and the previous application version are the application rollback path; preserve a database backup before rolling back schema changes. No documentation changes are pushed by the web app.
|
||||
|
||||
+43
-1
@@ -121,6 +121,44 @@ def _documentation_status(project, state):
|
||||
'audit_state': state.audit_state if state else {}}
|
||||
|
||||
|
||||
def _docs_sync_result(project, expected_remote_commit=None):
|
||||
user = _actor('projects:write')
|
||||
p = _project(user, project, write=True)
|
||||
if expected_remote_commit is not None and not documentation.HASH_RE.fullmatch(expected_remote_commit):
|
||||
raise ValidationError('Expected remote commit must be a full Git commit hash.')
|
||||
if not p.git_repository_url:
|
||||
return {'status': 'failed', 'project_id': str(p.pk), 'expected_remote_commit': expected_remote_commit,
|
||||
'remote_head': None, 'indexed_commit': None, 'document_count': 0,
|
||||
'last_success_at': None, 'last_attempt_at': None, 'retry_after_seconds': None,
|
||||
'error': 'Configure a Git repository URL before refreshing documentation.',
|
||||
'freshness': 'No repository configured'}
|
||||
previous = DocumentationSync.objects.filter(project=p).first()
|
||||
previous_attempt = previous.last_attempt_at if previous else None
|
||||
previous_success = previous.last_success_at if previous else None
|
||||
state = documentation.sync_project(user, p, force=True)
|
||||
cooled_down = state.last_attempt_at == previous_attempt
|
||||
diverged = bool(expected_remote_commit and state.remote_head and state.remote_head != expected_remote_commit)
|
||||
if state.sync_token:
|
||||
status = 'in_progress'
|
||||
elif cooled_down:
|
||||
status = 'already_current' if state.indexed_commit and state.remote_head == state.indexed_commit and not state.last_error else 'failed'
|
||||
elif state.last_error or state.last_success_at == previous_success:
|
||||
status = 'failed'
|
||||
elif previous and previous.indexed_commit == state.indexed_commit and previous.indexed_repository_url == state.indexed_repository_url:
|
||||
status = 'already_current'
|
||||
else:
|
||||
status = 'completed'
|
||||
if diverged:
|
||||
status = 'failed'
|
||||
return {'status': status, 'project_id': str(p.pk), 'expected_remote_commit': expected_remote_commit,
|
||||
'remote_head': state.remote_head or None, 'indexed_commit': state.indexed_commit or None,
|
||||
'document_count': ProjectDocument.objects.filter(project=p).count(),
|
||||
'last_success_at': state.last_success_at.isoformat() if state.last_success_at else None,
|
||||
'last_attempt_at': state.last_attempt_at.isoformat() if state.last_attempt_at else None,
|
||||
'retry_after_seconds': 30 if cooled_down else None,
|
||||
'error': ('Observed remote commit differs from expected commit.' if diverged else state.last_error or ('Refresh is cooling down; retry shortly.' if cooled_down and status == 'failed' else None)),
|
||||
'freshness': documentation.sync_status(p, state)}
|
||||
|
||||
def _docs_offset(cursor, token):
|
||||
if not cursor:
|
||||
return 0
|
||||
@@ -181,6 +219,10 @@ def create_server():
|
||||
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='Refresh a project’s read-only Git documentation index on demand. Requires project write access. The synchronous, bounded refresh shares the UI cooldown and retains the last good index on failure; it does not audit document accuracy.')
|
||||
async def docs_sync(project: str, expected_remote_commit: str | None = None) -> dict[str, Any]:
|
||||
return await sync_to_async(lambda: _safe(lambda: _docs_sync_result(project, expected_remote_commit)))()
|
||||
|
||||
@server.tool(structured_output=True, description='List indexed Git Markdown documents in an accessible project. Paths and source commits are returned without full content.')
|
||||
async def docs_list(project: str, path: str = '', limit: int = 50, cursor: str = '') -> dict[str, Any]:
|
||||
def run():
|
||||
@@ -736,7 +778,7 @@ def create_server():
|
||||
async def system_capabilities() -> dict[str, Any]:
|
||||
_actor()
|
||||
return {'scopes': ['projects:read', 'projects:write'], 'max_page_size': 100, 'version': '0.3',
|
||||
'transport': 'streamable_http', 'documentation': ['docs_list', 'docs_search', 'docs_read', 'docs_history', 'docs_diff'],
|
||||
'transport': 'streamable_http', 'documentation': ['docs_sync', 'docs_list', 'docs_search', 'docs_read', 'docs_history', 'docs_diff'],
|
||||
'card_moves': {'same_project': 'cards_move', 'between_projects': 'cards_move_project'}}
|
||||
|
||||
return server
|
||||
|
||||
@@ -9,13 +9,13 @@ from unittest.mock import patch
|
||||
from asgiref.sync import async_to_sync
|
||||
from django.contrib.auth import get_user_model
|
||||
from django.core.exceptions import ValidationError
|
||||
from django.test import Client, TestCase, override_settings
|
||||
from django.test import Client, TestCase, TransactionTestCase, override_settings
|
||||
from django.urls import reverse
|
||||
from django.utils import timezone
|
||||
from mcp.server.auth.provider import AccessToken
|
||||
from mcp.server.mcpserver.exceptions import ToolError
|
||||
|
||||
from mcp_server.server import create_server
|
||||
from mcp_server.server import create_server, _docs_sync_result, _safe
|
||||
from .documentation import (_fetch_snapshot, _git_env, _repository_url, audit_status,
|
||||
document_diff, document_history, historical_document,
|
||||
normal_path, sync_project)
|
||||
@@ -211,3 +211,60 @@ class DocumentationTests(TestCase):
|
||||
with self.captureOnCommitCallbacks(execute=True):
|
||||
self.project.delete()
|
||||
self.assertFalse(mirror.exists())
|
||||
|
||||
|
||||
class DocumentationMcpSyncTests(TransactionTestCase):
|
||||
"""Exercise the sync handler without the in-process MCP async bridge."""
|
||||
|
||||
def setUp(self):
|
||||
users = get_user_model()
|
||||
self.owner = users.objects.create_user('sync-owner', password='password')
|
||||
self.viewer = users.objects.create_user('sync-viewer', password='password')
|
||||
self.project = create_project(self.owner, name='MCP sync test',
|
||||
git_repository_url='https://git.jorendegraaf.eu/owner/project.git')
|
||||
Membership.objects.create(project=self.project, user=self.viewer, role='viewer')
|
||||
|
||||
def snapshot(self):
|
||||
markdown = '# Read me\n'
|
||||
document = ProjectDocument(project=self.project, path='docs/README.md', title='Read me',
|
||||
headings=['Read me'], markdown=markdown, content_hash=hashlib.sha256(markdown.encode()).hexdigest(),
|
||||
source_commit='a' * 40)
|
||||
return (self.project.git_repository_url, 'refs/heads/main', 'a' * 40, timezone.now(), [document], {})
|
||||
|
||||
def test_mcp_sync_permissions_metadata_cooldown_and_failure(self):
|
||||
server = create_server()
|
||||
def call(arguments):
|
||||
return _safe(lambda: _docs_sync_result(**arguments))
|
||||
self.assertIn('docs_sync', [tool.name for tool in server._tool_manager.list_tools()])
|
||||
owner = AccessToken(token='test', client_id='test', scopes=['projects:read', 'projects:write'], subject=str(self.owner.pk))
|
||||
read_only = AccessToken(token='test', client_id='test', scopes=['projects:read'], subject=str(self.owner.pk))
|
||||
viewer = AccessToken(token='test', client_id='test', scopes=['projects:read', 'projects:write'], subject=str(self.viewer.pk))
|
||||
args = {'project': str(self.project.pk)}
|
||||
with patch('mcp_server.server.get_access_token', return_value=read_only):
|
||||
with self.assertRaisesRegex(ToolError, 'projects:write authorization required'):
|
||||
call(args)
|
||||
with patch('mcp_server.server.get_access_token', return_value=viewer):
|
||||
with self.assertRaisesRegex(ToolError, 'not_found|permission_denied'):
|
||||
call(args)
|
||||
with patch('mcp_server.server.get_access_token', return_value=owner):
|
||||
with patch('projects.documentation._fetch_snapshot', return_value=self.snapshot()) as fetch:
|
||||
first = call(args)
|
||||
self.assertEqual(first['status'], 'completed')
|
||||
self.assertEqual(first['document_count'], 1)
|
||||
self.assertEqual(first['indexed_commit'], 'a' * 40)
|
||||
self.assertIsNotNone(first['last_success_at'])
|
||||
again = call(args)
|
||||
self.assertEqual(again['status'], 'already_current')
|
||||
self.assertIsNotNone(again['retry_after_seconds'])
|
||||
diverged = call({**args, 'expected_remote_commit': 'b' * 40})
|
||||
self.assertEqual(diverged['status'], 'failed')
|
||||
self.assertIn('differs', diverged['error'])
|
||||
fetch.assert_called_once()
|
||||
DocumentationSync.objects.filter(project=self.project).update(last_attempt_at=timezone.now() - timedelta(minutes=2))
|
||||
from .documentation import DocumentationError
|
||||
with patch('projects.documentation._fetch_snapshot', side_effect=DocumentationError('fetch unavailable')):
|
||||
failed = call(args)
|
||||
self.assertEqual(failed['status'], 'failed')
|
||||
self.assertEqual(failed['indexed_commit'], 'a' * 40)
|
||||
self.assertIn('fetch unavailable', failed['error'])
|
||||
self.assertTrue(ProjectDocument.objects.filter(project=self.project, path='docs/README.md').exists())
|
||||
|
||||
Reference in New Issue
Block a user