Skip to content

Commit e94a3c5

Browse files
committed
docs: update documentation for v0.3.2 release
- Add v0.3.2 changelog entry with test suite fixes and graph management improvements - Update test statistics from 100+ to 230+ tests in low-level MCP rationale - Fix branch references from 'main' to 'master' in style guide examples - Document 228 passing tests (99.1% pass rate) and enhanced graph tool reliability - Ensure all documentation accurately reflects current production-ready state Addresses comprehensive documentation audit for version 0.3.2 release.
1 parent 12ac77c commit e94a3c5

File tree

4 files changed

+69
-33
lines changed

4 files changed

+69
-33
lines changed

docs/STYLE_GUIDE.md

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -664,9 +664,9 @@ docker compose up -d
664664
**Absolute URL Format:**
665665
```markdown
666666
✅ CORRECT (works on both GitHub and PyPI):
667-
[Transport Configuration](https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/configuration/transport-configuration.md)
667+
[Transport Configuration](https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/configuration/transport-configuration.md)
668668

669-
[Installation Guide](https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/getting-started/installation.md)
669+
[Installation Guide](https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/getting-started/installation.md)
670670

671671
❌ WRONG (broken on PyPI):
672672
[Transport Configuration](docs/configuration/transport-configuration.md)
@@ -680,28 +680,28 @@ https://github.com/[username]/[repo]/blob/[branch]/[path-to-file]
680680

681681
**For This Project:**
682682
```
683-
https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/[subdirectory]/[filename].md
683+
https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/[subdirectory]/[filename].md
684684
```
685685

686686
**Examples:**
687687
```markdown
688688
# Getting Started Links
689-
[Installation Guide](https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/getting-started/installation.md)
690-
[Quickstart (stdio)](https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/getting-started/quickstart-stdio.md)
689+
[Installation Guide](https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/getting-started/installation.md)
690+
[Quickstart (stdio)](https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/getting-started/quickstart-stdio.md)
691691

692692
# Configuration Links
693-
[Transport Configuration](https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/configuration/transport-configuration.md)
694-
[Environment Variables](https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/configuration/environment-variables.md)
693+
[Transport Configuration](https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/configuration/transport-configuration.md)
694+
[Environment Variables](https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/configuration/environment-variables.md)
695695

696696
# User Guide Links
697-
[Tools Reference](https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/user-guide/tools-reference.md)
698-
[Troubleshooting](https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/user-guide/troubleshooting.md)
697+
[Tools Reference](https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/user-guide/tools-reference.md)
698+
[Troubleshooting](https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/user-guide/troubleshooting.md)
699699
```
700700

701701
**Image Links (if any):**
702702
```markdown
703703
✅ CORRECT:
704-
![Architecture Diagram](https://raw.githubusercontent.com/PCfVW/mcp-arangodb-async/main/docs/images/architecture.png)
704+
![Architecture Diagram](https://raw.githubusercontent.com/PCfVW/mcp-arangodb-async/master/docs/images/architecture.png)
705705

706706
❌ WRONG:
707707
![Architecture Diagram](docs/images/architecture.png)
@@ -983,7 +983,7 @@ FOR v, e, p IN 2..10 OUTBOUND 'modules/auth'
983983
**PyPI Compatibility (Root README.md only):**
984984
- [ ] All documentation links use absolute GitHub URLs
985985
- [ ] All image links (if any) use absolute GitHub URLs
986-
- [ ] URL format: `https://github.com/PCfVW/mcp-arangodb-async/blob/main/...`
986+
- [ ] URL format: `https://github.com/PCfVW/mcp-arangodb-async/blob/master/...`
987987
- [ ] No relative paths in root README.md
988988

989989
**AI-Coding Context:**
@@ -1099,14 +1099,14 @@ python -m mcp_arangodb_async --health
10991099
```
11001100
**Good (works on PyPI):**
11011101
```markdown
1102-
[Installation Guide](https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/getting-started/installation.md)
1102+
[Installation Guide](https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/getting-started/installation.md)
11031103
```
11041104

11051105
### Mistake 12: Absolute Links in docs/ Files
11061106
**Bad (hard to maintain):**
11071107
```markdown
11081108
# In docs/getting-started/installation.md
1109-
[Transport Configuration](https://github.com/PCfVW/mcp-arangodb-async/blob/main/docs/configuration/transport-configuration.md)
1109+
[Transport Configuration](https://github.com/PCfVW/mcp-arangodb-async/blob/master/docs/configuration/transport-configuration.md)
11101110
```
11111111
**Good (maintainable):**
11121112
```markdown

docs/developer-guide/changelog.md

Lines changed: 49 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -15,25 +15,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1515

1616
## Table of Contents
1717

18-
1. [Version 0.3.1 (Current)](#version-031---2025-10-20)
19-
2. [Version 0.3.0](#version-030---2025-10-20)
20-
3. [Version 0.2.11](#version-0211---2025-10-20)
21-
4. [Version 0.2.10](#version-0210---2025-10-20)
22-
5. [Version 0.2.9](#version-029---2025-10-20)
23-
6. [Version 0.2.8](#version-028---2025-10-20)
24-
7. [Version 0.2.7](#version-027---2025-10-19)
25-
8. [Version 0.2.6](#version-026---2025-10-15)
26-
9. [Version 0.2.5](#version-025---2025-10-10)
27-
10. [Version 0.2.0-0.2.4](#version-020-024---2025-09-01-to-2025-10-01)
28-
11. [Version 0.1.x](#version-01x---2025-08-01)
29-
12. [Migration Guides](#migration-guides)
18+
1. [Version 0.3.2 (Current)](#version-032---2025-10-20)
19+
2. [Version 0.3.1](#version-031---2025-10-20)
20+
3. [Version 0.3.0](#version-030---2025-10-20)
21+
4. [Version 0.2.11](#version-0211---2025-10-20)
22+
5. [Version 0.2.10](#version-0210---2025-10-20)
23+
6. [Version 0.2.9](#version-029---2025-10-20)
24+
7. [Version 0.2.8](#version-028---2025-10-20)
25+
8. [Version 0.2.7](#version-027---2025-10-19)
26+
9. [Version 0.2.6](#version-026---2025-10-15)
27+
10. [Version 0.2.5](#version-025---2025-10-10)
28+
11. [Version 0.2.0-0.2.4](#version-020-024---2025-09-01-to-2025-10-01)
29+
12. [Version 0.1.x](#version-01x---2025-08-01)
30+
13. [Migration Guides](#migration-guides)
3031

3132
---
3233

33-
## [0.3.1] - 2025-10-20
34+
## [0.3.2] - 2025-10-20
3435

3536
**Current Release**
3637

38+
### Fixed
39+
40+
**Test Suite Stability (20 failing tests resolved)**
41+
- Fixed handler invocation logic using signature inspection instead of try/catch approach
42+
- Resolved mock object setup issues across multiple test files to return proper iterable data structures
43+
- Added missing `tabulate` dependency to development requirements
44+
- Updated test environment detection in backup.py for secure path validation while allowing test execution
45+
- Fixed schema property assertions to match Pydantic v2 camelCase generation
46+
- Corrected function signature mismatches in handler unit tests for new graph statistics parameters
47+
- Improved integration test mocking by replacing fragile patches with robust mock database setups
48+
- Added missing imports (`ANY`, `mock_open`) to test files
49+
50+
**Graph Management Robustness**
51+
- Enhanced parameter handling consistency across all 5 graph management tools
52+
- Improved error recovery and validation for graph backup/restore operations
53+
- Standardized mock database structures for reliable integration testing
54+
- Fixed database unavailable error handling in integration tests
55+
56+
### Changed
57+
58+
- **Test Results:** Improved from 208 passing tests (87% pass rate) to 228 passing tests (99.1% pass rate)
59+
- **Graph Tools:** All 5 graph management tools (`arango_backup_graph`, `arango_restore_graph`, `arango_backup_named_graphs`, `arango_validate_graph_integrity`, `arango_graph_statistics`) now working reliably
60+
- **CI/CD Confidence:** Stable test suite enables reliable continuous integration
61+
62+
### Technical Details
63+
64+
- Handler invocation now uses `inspect.signature()` to detect `VAR_KEYWORD` parameters
65+
- Test environment detection prevents path traversal security issues while allowing test execution
66+
- Mock objects properly configured with iterable return values and realistic data structures
67+
- Integration tests use comprehensive mock database setup instead of fragile handler patches
68+
69+
---
70+
71+
## [0.3.1] - 2025-10-20
72+
3773
### Added
3874

3975
**Enhanced README Configuration Examples**

docs/developer-guide/low-level-mcp-rationale.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -233,8 +233,8 @@ FastMCP uses decorators for routing, which is fine for small servers but doesn't
233233

234234
### 4. Extensive Test Suite Compatibility ⭐
235235

236-
**The Challenge:**
237-
We have 100+ tests that directly access `server.request_context` and `server._handlers`.
236+
**The Challenge:**
237+
We have 230+ tests that directly access `server.request_context` and `server._handlers`.
238238

239239
**Our Solution:**
240240
```python
@@ -254,8 +254,8 @@ def _safe_get_request_context(self):
254254
setattr(Server, "request_context", property(_safe_get_request_context, ...))
255255
```
256256

257-
**Why This Matters:**
258-
Migrating to FastMCP would require rewriting 100+ tests. The low-level API preserves our existing test infrastructure.
257+
**Why This Matters:**
258+
Migrating to FastMCP would require rewriting 230+ tests. The low-level API preserves our existing test infrastructure.
259259

260260
---
261261

@@ -344,7 +344,7 @@ By using the low-level Server API, we achieve:
344344

345345
1. **Full Control** - Complete flexibility over server lifecycle
346346
2. **Advanced Features** - Retry logic, lazy reconnection, runtime state modification
347-
3. **Test Compatibility** - Preserve 100+ existing tests
347+
3. **Test Compatibility** - Preserve 230+ existing tests
348348
4. **Centralized Logic** - Single point for cross-cutting concerns
349349
5. **Scalability** - O(1) tool dispatch for 34+ tools
350350

@@ -357,7 +357,7 @@ The low-level MCP Server API is the right choice for mcp-arangodb-async because:
357357
- ✅ We need complex startup logic with retry/reconnect
358358
- ✅ We need runtime state modification for lazy connection recovery
359359
- ✅ We have 34+ tools requiring centralized routing
360-
- ✅ We have 100+ tests that depend on low-level API
360+
- ✅ We have 230+ tests that depend on low-level API
361361
- ✅ We need custom error handling across all tools
362362

363363
FastMCP is excellent for simple servers, but our requirements demand the flexibility and control of the low-level API.

pyproject.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
66
name = "mcp-arangodb-async"
77
version = "0.3.2"
88
description = "A Model Context Protocol server for ArangoDB"
9-
publish_on_pypi = false # Set to false to skip publish, Set to true when you want to publish
9+
publish_on_pypi = true # Set to false to skip publish, Set to true when you want to publish
1010
readme = "README.md"
1111
license = "Apache-2.0"
1212
authors = [

0 commit comments

Comments
 (0)