Skip to content

Tutorial Alfresco PGVector and MCP Inspector

Piergiorgio Lucidi edited this page Nov 13, 2026 · 2 revisions

Tutorial: End-to-End Ingestion from Alfresco Content Services to PGVector and Zero-Trust MCP Querying with MCP Inspector

This hands-on tutorial walks you through setting up a complete, self-contained local OpenCrawling environment with Alfresco Content Services (Community 26.1.0), PostgreSQL + pgvector, Apache Kafka, Ollama (mxbai-embed-large), the OpenCrawling Admin UI, and MCP Inspector.

By the end of this tutorial, you will be able to:

  1. Start the full decoupled Docker Compose tutorial stack locally.
  2. Provision test folders, documents, users, groups, and Zero-Trust ACLs (including broken inheritance and an explicit DENIED rule) in Alfresco Content Services.
  3. Configure the Alfresco Repository Connector and a PGVector Ingestion Job via the Admin UI or REST API.
  4. Execute the ingestion job and inspect vector chunks and security metadata stored in pgvector.
  5. Verify execution metrics, downloadable compliance artifacts (CSV, Parquet, JSON), and run DuckDB SQL queries in the Reports & Audit panel of the Admin UI.
  6. Install, configure, and use MCP Inspector (both Web UI and CLI) to inspect exposed tools, verify Zero-Trust permission enforcement across four user personas, and run live semantic search, document retrieval, and repository discovery queries.

All ready-to-run Docker Compose files, sample documents, JSON payloads, MCP Inspector configs, and automation scripts are included in the repository under tutorials/.


Architecture & Scenario Overview

flowchart LR
    Alfresco["Alfresco 26.1.0 + Share & Workspace<br/>(:8081)"] -->|"1. Crawl Docs + ACLs"| Runtime["OpenCrawling Runtime & Admin UI<br/>(oc-admin-ui :3000 / API :8080)"]
    Runtime -->|"2. Claim Check (/data/claims)<br/>& Kafka Topics"| Consumers["Decoupled Consumers<br/>(Tika 4 -> Ollama 1024d -> Writer)"]
    Consumers -->|"3. Vectors + Security ACLs"| PG[("PGVector (:5432)<br/>vector_store_1024")]
    Runtime -->|"4. Execution Audit Ledger"| Reports[("Parquet / CSV / JSON<br/>(/data/reports) + DuckDB")]
    Inspector["MCP Inspector<br/>(Web UI & CLI)"] -->|"5. Streamable HTTP (:8080/mcp)<br/>ACL-Enforced Queries"| Runtime
    Runtime -->|"Pre-filtered Search<br/>& Live Discovery"| PG
    Runtime -.->|"exploreRepositoryTree<br/>queryRepositoryDryRun"| Alfresco
Loading

Tutorial Files in the Repository

tutorials/
├── config/
│   ├── alfresco-connector.json            # Alfresco_Tutorial repository connector payload
│   └── alfresco-pgvector-job.json         # Alfresco_Tutorial_PGVector_Job payload
├── data/
│   └── alfresco/                          # Sample docs across 4 permission tiers
│       ├── public/company-handbook.txt
│       ├── finance/q4-financial-forecast.txt
│       ├── engineering/zero-trust-architecture.txt
│       └── executive/board-resolution-2026.txt
├── docker/
│   └── docker-compose-alfresco-pgvector-mcp.yml
├── mcp/
│   ├── mcp-inspector-config.json          # MCP Inspector server definition (/mcp & /sse)
│   └── sample-queries.json                # Ready-to-paste arguments for 4 caller personas
└── scripts/
    ├── start-env.sh                       # Boots stack and waits for all health checks
    ├── provision-alfresco-data.sh         # Creates users, groups, docs & ACLs in Alfresco
    ├── configure-opencrawling.sh          # Registers connector/job & triggers crawl via REST API
    ├── verify-tutorial.sh                 # Verifies PGVector, Reports/DuckDB, & MCP Inspector CLI
    └── stop-env.sh                        # Stops stack (pass --clean to remove volumes)

Prerequisites

Requirement Recommended Version Purpose
Docker & Docker Compose Docker 24+, Compose v2 (docker compose) Runs Alfresco, PGVector, Kafka, Ollama, OpenCrawling services, and Admin UI
RAM allocated to Docker >= 8 GB (12 GB recommended) Alfresco Repository, Transform AIO, ActiveMQ, Kafka, Ollama, and JVM microservices run concurrently
Node.js & npm Node.js 18+ (includes npx) Installs and launches @modelcontextprotocol/inspector
curl & jq Recent CLI versions Used by provisioning, configuration, and verification scripts

Clone the repository and navigate to its root directory:

git clone https://github.com/opencrawling/opencrawling.git
cd opencrawling

Step 1: Start the Local Environment with Docker

The self-contained Compose file tutorials/docker/docker-compose-alfresco-pgvector-mcp.yml starts the entire tutorial topology on a dedicated bridge network (opencrawling-tutorial-network):

  • Alfresco Content Services & UIs: alfresco (Community 26.1.0), share (alfresco/alfresco-share:26.1.0), content-app (alfresco/alfresco-content-app:7.5.0, the open-source Community counterpart to Enterprise Digital Workspace), and proxy (traefik:3.6) exposing /alfresco, /share/, /workspace/, and /content-app/ on host port 8081, plus transform-core-aio (8090), postgres-alfresco (5433), and activemq (8161 / 61616). Alfresco runs with -Dindex.subsystem.name=noindex for fast, low-memory startup in Folder Traversal crawl mode. (Note: quay.io/alfresco/alfresco-digital-workspace requires Enterprise Quay credentials, so this Community stack bundles public alfresco/alfresco-content-app:7.5.0 from Docker Hub.)
  • Infrastructure: postgres-vector (pgvector/pgvector:pg17 on port 5432), redis (redis/redis-stack:7.4.0-v8 on port 6379 / Insight 8001), ollama (ollama/ollama:0.40.5 on port 11434), ollama-model-puller (automatically pulls mxbai-embed-large), and kafka (apache/kafka:3.7.0 on port 9092).
  • OpenCrawling Services: oc-ingestion-consumer, oc-embedding-consumer (8082), oc-writer-consumer (configured for 1024-dimensional embeddings into vector_store_1024), oc-mcp-server (8080, aliased as opencrawling-backend with Discovery MCP tools enabled), and oc-admin-ui (3000).

Start the environment and wait for every health probe to pass:

./tutorials/scripts/start-env.sh

Tip

By default, start-env.sh uses the published ghcr.io/opencrawling/*:latest images. If you want to build the OpenCrawling containers from your local source checkout instead, run:

BUILD_IMAGES=true ./tutorials/scripts/start-env.sh

Once startup finishes, verify the exposed endpoints:

Service Local URL / Connection Credentials / Notes
OpenCrawling Admin UI http://localhost:3000 Proxies /api, /ws, /v3, and /swagger-ui to opencrawling-backend:8080
OpenCrawling Backend & Swagger UI http://localhost:8080/swagger-ui.html Health check: GET http://localhost:8080/api/system/status
OpenCrawling MCP Server http://localhost:8080/mcp Streamable HTTP (SPRING_AI_MCP_SERVER_PROTOCOL=STREAMABLE)
Alfresco Share UI http://localhost:8081/share/ admin / admin (or alice, bob, charlie / Password123!) — Classic Repository & Manage Permissions UI
Alfresco Content App (Digital Workspace Community) http://localhost:8081/workspace/ (alias: /content-app/) admin / admin (or test personas) — Modern ADF Workspace UI (alfresco/alfresco-content-app:7.5.0)
Alfresco REST API v1 http://localhost:8081/alfresco/api/-default-/public/alfresco/versions/1 User: admin / Password: admin (routed via Traefik proxy on port 8081)
PostgreSQL + pgvector localhost:5432 DB: opencrawling, User: opencrawling, Password: opencrawling_password

(If you want to verify containers manually at any time: docker compose -f tutorials/docker/docker-compose-alfresco-pgvector-mcp.yml ps.)


Step 2: Prepare Test Documents and Permissions in Alfresco Content Services

To thoroughly test Zero-Trust ACL filtering during RAG search and document retrieval, we will create three users, two groups, and four documents under /opencrawling-tutorial covering every major permission pattern:

Test Identities & Permission Matrix

  • Users: alice, bob, charlie
  • Groups:
    • GROUP_engineering: alice, bob
    • GROUP_finance: alice, charlie
Alfresco Path Document Title Inheritance Effective Alfresco ACL Expected Access
/opencrawling-tutorial/public/company-handbook.txt ACME Enterprise Handbook Disabled GROUP_EVERYONE (ALLOWED) Everyone (guest, charlie, bob, alice)
/opencrawling-tutorial/finance/q4-financial-forecast.txt ACME Q4 2026 Financial Forecast Disabled GROUP_finance (ALLOWED) charlie, alice
/opencrawling-tutorial/engineering/zero-trust-architecture.txt Zero-Trust RAG Architecture Blueprint Parent: disabled; Doc: inherits + local DENY GROUP_engineering (ALLOWED), bob (explicit DENIED) alice only (bob is blocked by explicit deny!)
/opencrawling-tutorial/executive/board-resolution-2026.txt Board Resolution 2026-11 Disabled alice (ALLOWED) alice only

Note

Notice two key Alfresco ACL behaviors that OpenCrawling preserves end-to-end:

  1. Alfresco prefixes custom group authorities with GROUP_ (for example, GROUP_finance and GROUP_engineering).
  2. Explicit Deny Precedence: bob belongs to GROUP_engineering, which grants access to the engineering folder, yet bob has an explicit DENIED ACE on zero-trust-architecture.txt. OpenCrawling records that deny in security_denied_read and blocks bob even though his group is allowed.

Option A: Automated Provisioning (Recommended)

Run the provisioning script, which uses the Alfresco Core REST API v1 to create the users, groups, folder hierarchy, content files from tutorials/data/alfresco/, and ACLs, and saves the generated Alfresco Node UUIDs to tutorials/data/.provisioned-nodes.json:

./tutorials/scripts/provision-alfresco-data.sh
Option B: How the Same Data & Permissions Are Configured Manually via Alfresco REST API v1 / Share UI

If you prefer creating or modifying permissions manually via Alfresco Share UI or curl against http://localhost:8081/alfresco/api/-default-/public/alfresco/versions/1:

  1. Create users (POST /people): alice, bob, charlie.
  2. Create groups & memberships (POST /groups and POST /groups/{groupId}/members with {"id":"<user>","memberType":"PERSON"}): create GROUP_engineering (alice, bob) and GROUP_finance (alice, charlie).
  3. Create the /opencrawling-tutorial folder tree (POST /nodes/-root-/children with {"name":"opencrawling-tutorial","nodeType":"cm:folder"}, then public, finance, engineering, executive).
  4. Disable permission inheritance and set folder ACLs (PUT /nodes/{folderId}?include=permissions):
    {
      "permissions": {
        "isInheritanceEnabled": false,
        "locallySet": [
          { "authorityId": "GROUP_finance", "name": "Consumer", "accessStatus": "ALLOWED" }
        ]
      }
    }
  5. Upload files (POST /nodes/{folderId}/children with nodeType: "cm:content", followed by PUT /nodes/{nodeId}/content).
  6. Add the explicit DENIED rule on zero-trust-architecture.txt (PUT /nodes/{archNodeId}?include=permissions):
    {
      "permissions": {
        "isInheritanceEnabled": true,
        "locallySet": [
          { "authorityId": "bob", "name": "Consumer", "accessStatus": "DENIED" }
        ]
      }
    }

Option C: Inspect the Permission Schema Visually in Alfresco Share & Content App (Workspace)

Once provisioned, you can inspect both the configured ACL rules and each persona's live repository view directly in your browser before crawling:

  1. Inspect configured ACLs & broken inheritance (admin / admin):
    • Alfresco Share (http://localhost:8081/share/): Sign in as admin / admin, open Repository in the top navigation bar, navigate into opencrawling-tutorial, hover over any folder (public, finance, engineering, executive) or document, and click Manage Permissions. You can see Inherit Permissions turned off on each subfolder together with the locally assigned ALLOWED rules (GROUP_EVERYONE, GROUP_finance, GROUP_engineering, alice).
    • Alfresco Content App / Workspace (http://localhost:8081/workspace/ or /content-app/): Sign in as admin / admin, click Repository in the left navigation sidebar, open opencrawling-tutorial, select a folder or document, and open More actions (...) -> Permissions (or right-click -> Permissions).
  2. Verify effective access per user (Password123!):
    • Sign into Share or Workspace as each persona (Password123!) and open Repository -> opencrawling-tutorial:
      • alice: sees all four folders (public, finance, engineering, executive) and all four documents.
      • charlie: sees public and finance (q4-financial-forecast.txt); engineering and executive are hidden.
      • bob: sees public and the engineering folder, but engineering/ appears empty because the explicit DENIED ACE on zero-trust-architecture.txt overrides his GROUP_engineering membership.

Note

  • Explicit DENIED visibility in Share UI: Alfresco Share's legacy Manage Permissions modal only lists ALLOWED permissions and omits explicit DENIED entries. To confirm bob's deny rule explicitly, inspect GET http://localhost:8081/alfresco/api/-default-/public/alfresco/versions/1/nodes/<nodeId>?include=permissions (or view the Content App permissions / log in as bob).
  • Browsing under -Dindex.subsystem.name=noindex: Because Solr/Elasticsearch is omitted to keep startup fast, use the Repository tree view rather than the Share/Workspace search bar — full semantic + metadata search is served by OpenCrawling + PGVector.

Step 3: Configure Connectors and the Ingestion Job on OpenCrawling

You can configure the connector and job visually in the OpenCrawling Admin UI (http://localhost:3000) or automatically via REST API. Both paths produce the exact same configuration stored on /app/data.

Option A: Configure via OpenCrawling Admin UI (http://localhost:3000)

3.1 Verify Pre-Seeded Transformation & Output Connectors

Open http://localhost:3000 and select Connectors in the left navigation bar. Two required connectors are already pre-seeded on startup:

  • Transformation tab: Ollama_Embedding_Default (http://ollama:11434, model mxbai-embed-large)
  • Output tab: PGVector_Output (PostgreSQL vector store at jdbc:postgresql://postgres-vector:5432/opencrawling, user opencrawling)

3.2 Create the Alfresco Repository Connector

  1. Stay on Connectors, select the Repository tab, and click New Connector (or New if an existing connector is highlighted).
  2. Fill in the repository fields (matching tutorials/config/alfresco-connector.json):
    • Connector Name: Alfresco_Tutorial
    • Connector Class: Alfresco Content Services Repository
    • Description: Alfresco Content Services (Tutorial Instance with Zero-Trust ACLs)
    • Alfresco API URL: http://alfresco:8080/alfresco/api/-default-/public/alfresco/versions/1 (Important: use http://alfresco:8080/..., the internal Docker network hostname and container port — not localhost:8081.)
    • Username: admin
    • Password: admin
    • Crawl Mode: Folder Tree Traversal (folder)
    • Root Folder Path: /opencrawling-tutorial
    • Batch Size: 100
    • Check Include Subfolders Recursively (true)
    • Check Fetch Binary Content Stream (true)
    • Check Include Access Control Lists (ACLs) & Collocated Security (true)
  3. Click Check Connection and verify the green banner shows Connection Verified & Reliable.
  4. Click Save.

3.3 Create the Ingestion Job

  1. Click Job Management in the left navigation bar and click New Pipeline Job.
  2. Configure the job fields (matching tutorials/config/alfresco-pgvector-job.json):
    • Job Name: Alfresco_Tutorial_PGVector_Job
    • Repository Connector (Source): Alfresco_Tutorial (AlfrescoRepositoryConnector)
    • Output Connector (Target Vector Store): PGVector_Output (VectorOutputConnector)
    • Authority Connector (Security Group, Optional): None (Public Access) (leave unset — collocated ACLs are extracted directly by Alfresco_Tutorial because Include Access Control Lists (ACLs) & Collocated Security is enabled)
    • Path / Directory: /opencrawling-tutorial
    • Transformation Connector: Local Ollama Embeddings using mxbai-embed-large (Ollama_Embedding_Default)
    • Pipeline Mode: RAG Mode (Default)
  3. Click Save to create the job.

Option B: Register Connector & Job via Script / REST API

You can execute the exact same API calls (POST /api/connectors/check, POST /api/connectors, POST /api/jobs) automatically with:

# Registers connector & job AND starts the job (set RUN_JOB=false to only register and start manually in UI)
./tutorials/scripts/configure-opencrawling.sh

Step 4: Execute the Job and Inspect PGVector Storage

  1. In Job Management (http://localhost:3000), locate Alfresco_Tutorial_PGVector_Job and click the play button (Start crawl job). (Skip if you already ran configure-opencrawling.sh with RUN_JOB=true.)
  2. Optionally switch to Real-time Logs in the left sidebar to watch Alfresco node traversal, Apache Tika text extraction, mxbai-embed-large embedding generation, and PGVector indexing.
  3. Return to Job Management: within a few seconds, the job status reaches Finished (stage: Completed, 4 documents).

Inspect Stored Chunks and ACL Metadata in PGVector

Verify that all 4 documents were embedded into the 1024-dimensional table vector_store_1024 along with normalized Zero-Trust metadata:

docker exec -i postgres-vector-tutorial psql -U opencrawling -d opencrawling -c "
SELECT metadata->>'name'                AS file_name,
       metadata->>'documentId'          AS doc_id,
       metadata->'security_read_keys'   AS read_keys,
       metadata->'security_denied_read' AS denied_read
FROM vector_store_1024
ORDER BY file_name;
"

Expected output:

            file_name            |                doc_id                |        read_keys        | denied_read
---------------------------------+--------------------------------------+-------------------------+--------------
 ["board-resolution-2026.txt"]   | 897f700c-2906-4daa-bf70-0c29064daab8 | ["u:alice"]             | []
 ["company-handbook.txt"]        | 7602638e-1427-416a-8263-8e1427916a18 | ["public"]              | []
 ["q4-financial-forecast.txt"]   | 0cb05b64-e429-4c3a-b05b-64e429fc3ac1 | ["g:group_finance"]     | []
 ["zero-trust-architecture.txt"] | 7338383c-4943-4fe5-b838-3c49431fe5f3 | ["g:group_engineering"] | ["user:bob"]
(4 rows)

Note

When a job is launched via JobController / Admin UI with decoupled Kafka consumers running, JobOrchestrator dispatches the job to Kafka consumers (which write the 4 chunks into vector_store_1024) while the direct PGVector_Output output path also writes to the default vector_store table. secureVectorSearch automatically resolves vector_store_1024 from the 1024-dimensional query vector; for listAccessibleSources (which scans all tables when dimensions is omitted), pass "dimensions": 1024 to avoid duplicate entries across both tables.


Step 5: Check Job Execution in the Reports & Audit Panel (Admin UI)

Open http://localhost:3000 and click Reports & Audit in the left navigation bar to open the Reports & Audit Ledger:

  1. Executive KPI Cards: Confirm summary totals across completed executions (Total Reports Generated, Total Documents Audited, Ingestion Success Rate, Total Tokens Consumed).
  2. Job Execution Reports Table: Locate the RAG badge row for Alfresco_Tutorial_PGVector_Job:
    • Status: SUCCESS
    • Documents: 4 total, 4 successful, 0 failed
    • Chunks & Tokens: 4 chunks, 400 tokens (ollama / mxbai-embed-large)
  3. Document Ledger Drill-Down: Click the execution row to inspect the paginated per-document ledger (ALL, SUCCESS, FAILED, SKIPPED), showing each Alfresco node UUID, claim-check URI (/data/claims/<uuid>_<filename>), per-document latency (duration_ms), chunk count, token count, and embedding model.
  4. Download Compliance Artifacts: Use the toolbar buttons (CSV Manifest, Parquet File, JSON Summary) to export the execution manifest (manifest_exec-<id>.csv), ZSTD-compressed Hive-partitioned Parquet file (mode=RAG/year=YYYY/month=MM/day=DD/job_<jobId>_exec_<execId>.parquet), or JSON summary.
  5. Run Analytical SQL with Embedded DuckDB:
    • Click Query with DuckDB to open the Serverless Parquet SQL Playground (DuckDB) modal.
    • Try querying status counts or per-document telemetry across the Parquet lakehouse files and click Execute Query:
SELECT document_id,
       source_uri,
       status,
       duration_ms,
       rag_chunk_count,
       rag_token_count
FROM read_parquet('/data/reports/**/*.parquet')
ORDER BY document_id;

You can also inspect the same data programmatically via REST API:

# List execution summaries
curl -sf http://localhost:3000/api/reports | jq '.[0]'

# Execute a DuckDB SQL aggregation over generated Parquet files
curl -sf -X POST http://localhost:3000/api/reports/query \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT status, count(*) AS cnt FROM read_parquet(\"/data/reports/**/*.parquet\") GROUP BY status"}' \
  | jq .

Step 6: Install, Configure, and Use MCP Inspector

Now verify how AI agents and MCP clients experience your ingested Alfresco content—and confirm that the OpenCrawling Secure MCP Server (McpVectorServer) enforces every Alfresco permission and explicit deny server-side.

6.1 Install & Launch MCP Inspector

MCP Inspector (@modelcontextprotocol/inspector) requires Node.js 18+ (npm / npx). You can run it directly with npx (zero permanent install) or install it globally:

# Optional global install:
npm install -g @modelcontextprotocol/inspector

# Verify CLI availability:
npx --yes @modelcontextprotocol/inspector --help

The repository already provides tutorials/mcp/mcp-inspector-config.json:

{
  "mcpServers": {
    "opencrawling-alfresco": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Launch the MCP Inspector Web UI preloaded with this configuration:

npx @modelcontextprotocol/inspector \
  --config tutorials/mcp/mcp-inspector-config.json \
  --server opencrawling-alfresco

This starts the MCP Inspector proxy/UI and opens it in your browser (typically http://localhost:6274 with the session auth token already attached in the URL).

6.2 Configure the Connection in MCP Inspector UI

If you launched npx @modelcontextprotocol/inspector without --config, configure the connection in the left pane manually:

  1. Transport Type: select Streamable HTTP.
  2. URL: enter http://localhost:8080/mcp.
  3. Click Connect. The status badge should turn green (Connected).

Note

The tutorial Docker stack runs oc-mcp-server with OPENCRAWLING_DISCOVERY_ALLOW_ASSERTED_IDENTITY=true and JWT enforcement disabled, which lets you pass userPrincipal and userRoles directly in MCP Inspector tool arguments to simulate different users. In production deployments configured with OAuth2/OIDC JWTs, the server ignores asserted identity parameters and extracts sub and groups directly from the verified bearer token.

6.3 Check Exposed Tools (Tools -> List Tools)

In MCP Inspector, open the Tools tab and click List Tools. You will see 11 tools exposed by oc-mcp-server:

  • RAG Search & Retrieval (McpVectorServer):
    • listAccessibleSources — Lists distinct indexed documents the caller is allowed to read.
    • secureVectorSearch — Semantic similarity search in pgvector pre-filtered and post-verified by caller ACLs.
    • getDocumentContent — Fetches full content and metadata by document URI/ID with fail-closed access verification.
    • openarch_search, openarch_fetch_document — Hyland OpenArch federated aliases backed by the same ACL gate.
  • Pre-Crawl Repository Discovery (DiscoveryMcpTools):
    • listRepositoryConnectors — Lists discoverable repository connectors (Alfresco_Tutorial).
    • exploreRepositoryTree — Walks live Alfresco folders/items on behalf of the caller without downloading content streams.
    • queryRepositoryDryRun — Estimates and previews what a crawl would match for the caller.
  • AIOps Observability (ObservabilityMcpTools):
    • fetchJobTraces, getErrorLogs, queryThroughputMetrics.

6.4 Execute Permission Tests & Queries in MCP Inspector

Ready-to-paste JSON arguments for every scenario are saved in tutorials/mcp/sample-queries.json. Test each persona in the Tools panel:

Scenario 1: Unprivileged User (guest) Sees Only Public Content

Select listAccessibleSources and run with:

{
  "userPrincipal": "guest",
  "userRoles": "",
  "dimensions": 1024
}

Observed result: Returns 1 document — company-handbook.txt (acl: "public", GROUP_EVERYONE). Finance, engineering, and executive documents are completely excluded.

Scenario 2: Finance Analyst (charlie) Searches with GROUP_finance

Select secureVectorSearch and run with:

{
  "query": "Q4 operating budget financial forecast",
  "userPrincipal": "charlie",
  "userRoles": "GROUP_finance",
  "maxResults": 10,
  "minScore": 0.0
}

Observed result: Returns q4-financial-forecast.txt (acl: "GROUP_finance", security_read_keys: ["g:group_finance"]) along with public company-handbook.txt, while never returning engineering or executive documents.

Scenario 3: Explicit DENIED Overrides Group Membership (bob)

Even though bob belongs to GROUP_engineering, bob has an explicit DENIED ACE on zero-trust-architecture.txt. Run secureVectorSearch as bob:

{
  "query": "zero-trust architecture rotating mTLS certificates",
  "userPrincipal": "bob",
  "userRoles": "GROUP_engineering",
  "maxResults": 10,
  "minScore": 0.0
}

Observed result: zero-trust-architecture.txt is blocked — bob only receives company-handbook.txt!

Now test direct URI retrieval enforcement by selecting getDocumentContent as bob using the board-resolution-2026.txt Node UUID (found in tutorials/data/.provisioned-nodes.json):

{
  "documentUri": "<BOARD_RESOLUTION_NODE_UUID>",
  "userPrincipal": "bob",
  "userRoles": "GROUP_engineering"
}

Observed result: Fails closed with isError: true and message "Document not found or access denied." (avoiding existence leakage).

Scenario 4: Privileged User (alice) Retrieves Restricted Content

Run secureVectorSearch and getDocumentContent as alice ("GROUP_engineering,GROUP_finance"):

{
  "query": "Project Horizon board resolution M&A strategy",
  "userPrincipal": "alice",
  "userRoles": "GROUP_engineering,GROUP_finance",
  "maxResults": 5,
  "minScore": 0.0
}

Observed result: Top match is board-resolution-2026.txt (acl: "alice", security_read_keys: ["u:alice"]). Calling listAccessibleSources as alice with "dimensions": 1024 returns all 4 documents, and getDocumentContent returns the full unredacted text referencing "Project Horizon".

Scenario 5: Compare Live Repository Discovery (exploreRepositoryTree)

Select exploreRepositoryTree and run once as bob ("GROUP_engineering") and once as alice ("GROUP_engineering,GROUP_finance"):

{
  "connector": "Alfresco_Tutorial",
  "userPrincipal": "bob",
  "userRoles": "GROUP_engineering"
}

Observed result:

  • bob: Sees only folders ["engineering", "public"] and document ["company-handbook.txt"] — live Alfresco ACLs hide zero-trust-architecture.txt as well as the finance and executive folders.
  • alice: Sees all 4 folders (engineering, executive, finance, public) and all 4 documents (zero-trust-architecture.txt, board-resolution-2026.txt, q4-financial-forecast.txt, company-handbook.txt).

6.5 Using MCP Inspector in CLI Mode (Automation & CI)

You can invoke the exact same MCP Inspector binary headlessly via --cli:

# List all MCP tools
npx --yes @modelcontextprotocol/inspector --cli \
  --config tutorials/mcp/mcp-inspector-config.json \
  --server opencrawling-alfresco \
  --format json -q \
  --method tools/list | jq '[.result.tools[].name]'

# Run secureVectorSearch as charlie (GROUP_finance)
npx --yes @modelcontextprotocol/inspector --cli \
  --config tutorials/mcp/mcp-inspector-config.json \
  --server opencrawling-alfresco \
  --format json -q \
  --method tools/call \
  --tool-name secureVectorSearch \
  --tool-args-json '{"query":"Q4 operating budget financial forecast","userPrincipal":"charlie","userRoles":"GROUP_finance","maxResults":10,"minScore":0.0}' \
  | jq -r '.result.content[0].text' | jq .

Or run the bundled automated end-to-end verification script covering PGVector SQL, Reports & Audit + DuckDB, and all MCP Inspector persona assertions:

./tutorials/scripts/verify-tutorial.sh

Step 7: Cleanup & Troubleshooting

Stop containers while keeping volumes and indexed data:

./tutorials/scripts/stop-env.sh

Remove containers, volumes, and tutorials/data/.provisioned-nodes.json completely:

./tutorials/scripts/stop-env.sh --clean

Common Troubleshooting

Symptom Cause Fix
Connection check fails on Alfresco_Tutorial Used http://localhost:8081/... in Connector URL Inside Docker, oc-mcp-server reaches Alfresco over the Compose network at http://alfresco:8080/alfresco/api/-default-/public/alfresco/versions/1
charlie or bob sees no group documents in MCP Omitted Alfresco's GROUP_ prefix in userRoles Pass GROUP_finance or GROUP_engineering (matching Alfresco authority IDs)
listAccessibleSources returns 8 rows instead of 4 Job triggered through Admin UI populates both vector_store (direct output) and vector_store_1024 (Kafka consumers) Pass "dimensions": 1024 in listAccessibleSources
jq errors parsing --cli JSON output @modelcontextprotocol/inspector --cli --format json wraps the JSON-RPC response under .result Access .result.tools and .result.content[0].text

Related Documentation

🗺️ Documentation


🎓 Tutorials


🧪 Testing


🤝 Community

Clone this wiki locally